Fuel Systems

General

This directory contains comprehensive guides for managing customer systems, equipment, and delivery window strategies (delivery estimation methods).

Core System Management

Adding Equipment

Learn how to add tanks, boilers, furnaces, and other equipment to a system. Includes detailed instructions for multi-tank configurations.

Key topics:

Editing a System

Modify existing systems safely with guidance on which changes are safe vs. those requiring caution.

Key topics:

Delivery Window Strategies (Estimation Methods)

Window Strategies

Choose and configure the delivery estimation method for each system. Window strategies determine how the system calculates when deliveries are needed.

Key topics:

Degree Day System

Temperature-based consumption estimation using heating degree days and usage rates.

Key topics:

Monitoring

Real-time tank level tracking using IoT monitoring devices identified by serial numbers.

Key topics:

Calendar Scheduling

Time-based recurring delivery schedules with seasonal controls and frequency settings.

Key topics:

Getting Started

  1. Create a system: Start with the Add System Guide

    • Choose system name and fuel type
    • Select a window strategy (Degree Day, Monitored, or Calendar)
    • Configure strategy-specific settings
    • Enable Auto Delivery toggle if needed

  2. Add equipment: Follow Adding Equipment to add tanks and appliances

  3. Configure delivery: Your window strategy determines how deliveries are triggered:

Quick Reference

System Concepts

Window Strategy Comparison

Strategy Configured In Triggers On Requires
Degree Day Degree Day tab Temperature data + usage rates Winter/summer rates, window boundaries
Monitored Tank Monitor tab Tank level readings Monitor serial number
Calendar Calendar tab Time intervals + rules Active schedule with frequency/dates

Configuration Locations

All window strategy settings are configured in the Add/Edit System dialog:

Common Workflow

  1. Navigate to Systems from Customer Dashboard
  2. Click Add System or Edit existing system
  3. Enter system name and select fuel type
  4. Choose window strategy: Degree Day, Monitored, or Calendar
  5. Configure in the appropriate tab:
    • Degree Day: Set usage rates and windows
    • Monitored: Enter serial number
    • Calendar: Save system first, then add schedules
  6. Enable Auto Delivery toggle if deliveries should be automatic
  7. Add custom attributes as needed
  8. Enter notes for drivers, routers, and office
  9. Submit to save
  10. Add equipment to the system

Adding a System Guide

A system represents a group of equipment that all share the same fill connection (the same delivery fill). For example, multiple manifolded tanks feeding the same appliance belong to one system. This guide shows how to create a system and configure its delivery window strategy.

Important: You can attach multiple physical tanks to the same equipment entry when they are manifolded to a single fill. This keeps projections and routing accurate for the shared capacity.

Prerequisites

Create a system

  1. Open the Customer Dashboard for the selected Customer and Location.

  2. Go to Systems in the overview (or use the Systems action in the header).

  3. Click Add System.

  4. The Add System dialog opens with multiple configuration sections.

  5. Complete the basic settings and select a window strategy.

  6. Configure the strategy-specific settings in the appropriate tab.

  7. Click Submit to save.

Basic system settings

Required fields

Toggles

Optional fields

Window strategy selection

Choose the delivery estimation method that best fits this system:

The selected strategy determines which configuration tab you'll use next.

See: Window Strategies Guide for detailed comparison and recommendations.

Strategy-specific configuration

Degree Day configuration

If you selected "Degree Day" as your window strategy:

Usage rates:

Delivery windows:

Actions available:

Monitored configuration

If you selected "Monitored" as your window strategy:

Required:

Optional:

Note: The submit button will be disabled until you provide a monitor serial number for monitored systems.

Calendar configuration

If you selected "Calendar" as your window strategy:

For new systems, calendar schedules must be configured after the system is saved. You'll see a warning message: "Save the system before managing calendar schedules."

After saving, you can create calendar schedules with:

Only one calendar schedule can be active at a time.

See: Calendar Scheduling Guide for detailed schedule management.

Understanding systems and fills

A system is a logical grouping of equipment that all connect to the same fill point:

This grouping ensures accurate capacity tracking, delivery projections, and routing.

Additional system fields

Fill Location Notes

Custom Attributes

Predefined fields:

Additional custom fields:

Next Delivery Notes

Driver Alerts:

Router Notes:

Office Notes

Next: Add equipment

After saving the system, add equipment under the system (tanks, boilers, furnaces, vaporizers, regulators, etc.).

For manifolded tanks feeding the same appliance/fill, attach multiple tanks to the same equipment set to represent one shared capacity.

See: Adding Equipment

Editing later

You can rename the system, adjust window strategy, or deactivate it. Be careful changing fill associations or window strategies after deliveries exist, as it can impact projections.

See: Editing a System

Editing a System Guide

This guide explains how to edit an existing system using the Edit System dialog and what each field and setting controls.

Prerequisites

Edit a system

  1. Navigate to Systems from the Customer Dashboard.

  2. Find the system you want to edit.

  3. Click Edit on the system.

  4. The Edit System dialog opens with all current settings.

  5. Make your changes and click Submit.

What you can edit

The Edit System dialog has the same structure as Add System, with all fields editable:

Basic system settings

System Name

Active toggle

Auto Delivery toggle

Fuel selector (Propane, Oil, etc.)

Window Strategy selector (Degree Day, Monitored, Calendar)

Usage multi-select

Window strategy tabs

After selecting a window strategy, configure its settings in the appropriate tab:

Degree Day Settings tab

Usage Rates:

Window boundaries:

Action buttons:

Info displays:

Tank Monitor tab

Monitor Serial Number

Monitor Barcode

Calendar Schedules tab

Manage recurring delivery schedules:

Additional editable fields

Fill Location Notes

Custom Attributes

Predefined fields:

Additional custom fields:

Next Delivery Notes

Driver Alerts:

Router Notes:

Office Notes

Safe edits (no delivery impact)

These changes can be made freely without affecting active deliveries:

Changes requiring caution

Deactivating the system (Active toggle off)

Impact:

When to use:

Best practice: Verify no pending deliveries exist before deactivating

Disabling Auto Delivery toggle

Impact:

When to use:

Changing Window Strategy

Impact:

Example: Switching from Degree Day to Monitored

Best practice: Configure the new strategy completely before switching

Changing Fuel type

Impact:

When to use: Only if the physical system has been converted (e.g., oil to propane)

Best practice:

Forcing Degree Day or Resetting Windows

Impact:

When to use:

Best practice: Document the reason in notes

Equipment management

Equipment is not edited directly in the system dialog. To manage equipment:

  1. View equipment list in the system details
  2. Click Edit on the specific equipment
  3. Use the Equipment dialog to modify
  4. See: Adding Equipment

Note: You cannot change which system equipment belongs to from this dialog. Edit the equipment itself to reassign it.

What you cannot edit

Validation and errors

The dialog validates entries before allowing submission:

Common validation errors:

Validation errors appear at the top or inline with red styling. The Submit button is disabled until all errors are resolved.

After saving changes

When you click Submit:

Note: Changes to window strategy or usage rates may cause immediate recalculation of delivery windows and target dates.

Deactivating vs. deleting a system

Deactivate (Active toggle off):

Delete (via delete action):

Best practice: Always deactivate rather than delete to maintain data integrity and history.

Adding Equipment Guide

This guide explains how to add equipment to a system using the Add/Edit Equipment dialog. Equipment represents physical components like tanks, regulators, filters, and other equipment.

Key concept: You can add multiple tanks to a system when they share the same fill connection. Each piece of equipment is tracked separately within the system.

Prerequisites

Add equipment to a system

  1. Navigate to the Systems section from the Customer Dashboard.

  2. Select the system you want to add equipment to.

  3. Click Add Tank or Add Equipment.

  4. The Add Equipment dialog opens with multiple sections.

  5. Fill out the required fields and click Add Equipment or Update Equipment.

Equipment types

The dialog supports these equipment types:

Basic Information section

Required fields

All three fields are required to proceed.

Equipment Details section

Serial Number

Optional fields

Installation & Inspection section

Both fields are optional:

Use date pickers to select dates.

Regulator Information (regulators only)

If you selected Type = Regulator, an additional section appears:

Required field

This field uses a date picker and is mandatory for regulator equipment.

Tank Information (tanks only)

If you selected Type = Tank, an additional section appears with three required fields:

Required fields (all with gallon suffix)

Example for a 275-gallon tank:

Multiple tanks on one system

When you have multiple tanks sharing the same fill connection:

  1. Add each tank as separate equipment to the same system
  2. Enter accurate Size, Recommended Capacity, and Optimum Delivery for each tank
  3. The system automatically aggregates capacity across all tanks for delivery calculations

Example setup:

This approach allows accurate tracking of individual tanks while calculating deliveries for the combined system.

Custom Attributes section

Always visible at the bottom of the dialog:

Predefined custom fields

Additional custom fields

Validation and submission

The dialog validates your entries:

The Add Equipment or Update Equipment button is disabled until all validation passes.

Dialog actions

After saving, the equipment appears in the system's equipment list and can be used for delivery projections, monitoring, and service tracking.

Editing or removing equipment

Delivery Strategies

Delivery Strategies

Understanding Window Strategies

Window strategies determine how deliveries are estimated and scheduled by selecting the calculation method used for each system. The window strategy is configured in the system edit dialog and determines which approach is used to trigger deliveries.

What are window strategies?

A window strategy defines the method used to calculate when a delivery is needed:

The window strategy determines which calculation approach takes priority for triggering deliveries for all equipment within that system.

Window strategy types

Degree Day Window

Uses outdoor temperature data to estimate fuel consumption and predict when refills are needed based on accumulated heating degree days.

Best for:

How it works:

See: Understanding Degree Days

Monitored Window

Uses real-time tank level data from IoT monitoring devices to trigger deliveries based on actual fuel levels.

Best for:

How it works:

See: Understanding Fuel Monitoring

Calendar Window

Uses recurring time-based schedules to plan deliveries at regular intervals regardless of consumption.

Best for:

How it works:

See: Understanding Calendar Schedules

Configuring window strategies

Window strategies are configured when adding or editing a system through the Add/Edit System dialog.

Basic system settings

At the top of the dialog:

Strategy-specific configuration tabs

Degree Day Settings Tab

Configuration fields:

Action buttons:

Tank Monitor Tab

Configuration fields:

Validation:

Calendar Schedules Tab

Schedule configuration:

Schedule actions:

Auto Delivery toggle

Controls whether the system should appear on the routing map & automatically generates delivery requests for calendar scheduling:

Delivery Strategies

Understanding Calendar Schedules

Calendar scheduling allows you to set up automatic delivery requests for your customers based on recurring patterns. When you post an invoice for a fuel delivery, the system automatically creates the next delivery request based on the schedule you've configured.

Key Features

Flexible Recurring Patterns

You can schedule deliveries to repeat at any interval you need:

Specific Day of the Week

If your customers prefer deliveries on certain days, you can set schedules to occur on:

When you set a day of the week, the system will automatically schedule the delivery on the next occurrence of that day after the interval passes.

Example: If you schedule "every 2 weeks on Friday," the system will always create delivery requests for Fridays, even if the exact 2-week interval would land on a different day.

Seasonal Schedules

Many customers have different needs throughout the year. Calendar scheduling supports seasonal patterns:

The system uses the month and day from your start and end dates, ignoring the year. This means your seasonal schedules automatically repeat every year without needing to update them.

Example: Set a schedule active from November 1 to March 31, and it will automatically activate every winter, year after year.

Pre-Set Delivery Volume

You can specify how many gallons or liters should be requested for each scheduled delivery. This helps your drivers know approximately how much fuel to bring.

How It Works

Setting Up a Schedule

For each fuel system (tank), you can create one or more calendar schedules with:

  1. Frequency - How often deliveries should occur (number and unit)
  2. Day of Week (Optional) - Which day deliveries should happen
  3. Start Date (Optional) - What month/day the schedule becomes active
  4. End Date (Optional) - What month/day the schedule becomes inactive
  5. Delivery Volume (Optional) - How many gallons/liters to request

Automatic Delivery Request Creation

When you post an invoice for a delivery:

  1. The system checks if there's an active calendar schedule for that fuel system
  2. It verifies the delivery date falls within the schedule's active period
  3. It calculates when the next delivery should occur
  4. It automatically creates a delivery request for that future date

The new delivery request includes:

Managing Active Schedules

You can have multiple schedules for the same system, but only one will create a delivery request per invoice posting. Schedules can be:

To stop a schedule from creating delivery requests, mark it as inactive rather than deleting it. This preserves the configuration if you need to reactivate it later.

Common Use Cases

Example 1: Summer Propane Fill-Ups

Scenario: A customer wants propane deliveries every 60 days during the summer months only.

Configuration:

Result: Every time you post an invoice between May and October, the system creates the next delivery request 60 days out. No deliveries are scheduled during winter months.

Example 2: Weekly Friday Deliveries

Scenario: A commercial customer receives heating oil every week on Fridays.

Configuration:

Result: After each delivery, the system automatically schedules the next delivery for the following Friday.

Example 3: Monthly Winter Fuel Oil

Scenario: A residential customer needs heating oil monthly during winter only.

Configuration:

Result: Monthly deliveries are scheduled from November through March each year. The schedule automatically reactivates each winter.

Example 4: Bi-Weekly Tuesday Deliveries (Winter Only)

Scenario: A customer wants deliveries every 2 weeks on Tuesdays, but only during the heating season.

Configuration:

Result: Deliveries are scheduled every other Tuesday during the specified months, automatically resuming each heating season.

Tips for Success

Setting Seasonal Boundaries

Choosing Day of Week

Delivery Volume Estimates

Multiple Schedules

Troubleshooting

No Delivery Request Created

If a delivery request isn't automatically created after posting an invoice:

Wrong Delivery Date

If the calculated delivery date seems incorrect:

Seasonal Schedule Not Activating

For schedules that should work across the year boundary (Nov-Mar):

Getting Started

To begin using calendar scheduling:

  1. Navigate to the fuel system you want to schedule
  2. Create a new calendar schedule
  3. Configure the frequency, optional day of week, and seasonal dates
  4. Set the delivery volume if desired
  5. Save the schedule
  6. Post the next invoice for that system - the delivery request will be created automatically

Calendar scheduling saves time by eliminating manual delivery request creation and ensures consistent service for your customers. Set it up once and let the system handle the rest!

Delivery Strategies

Understanding Degree Days

The degree day system predicts heating fuel consumption based on outdoor temperature. It's commonly used for automatic oil delivery scheduling to estimate when a customer will need a refill.

What is a degree day?

A degree day measures heating demand:

Example:

If it takes 5 HDD to burn 1 gallon of oil (K-factor = 5), then after 100 accumulated HDD, the customer has used approximately 20 gallons.

Key formulas

Daily heating degree days

$$ HDD_{day} = \max(0, T_{base} - T_{avg}) $$

Where:

Accumulated degree days

$$ HDD_{accumulated} = \sum_{i=1}^{n} HDD_i $$

Sum all daily HDDs since the last delivery.

K-factor (consumption rate)

The K-factor represents the relationship between degree days and gallons consumed:

$$ K = \frac{HDD}{gallons} $$

Example: If a customer used 200 gallons over 1000 HDD, then:

$$ K = \frac{1000}{200} = 5.0 $$

So it takes 5 HDD to consume 1 gallon.

Estimating gallons used

$$ gallons_{used} = \frac{HDD_{accumulated}}{K} $$

Remaining fuel estimate

$$ remaining = capacity - gallons_{used} $$

Where capacity is the effective tank capacity (total capacity minus a reserve buffer).

Triggering a delivery

Dispatch a delivery when:

$$ remaining \leq reserve_{threshold} $$

Typically, reserve threshold is 25-30% of capacity to avoid run-outs.

Configuration steps

1. Set base temperature

2. Determine K-factor

Initial K-factor (before delivery history):

Computed K-factor (after deliveries):

3. Initialize the system

On the first delivery (or when setting up):

The system will start accumulating degree days from the last delivery date.

4. Set minimum days between deliveries

Prevent too-frequent deliveries by setting a minimum interval (e.g., 14 or 21 days). Even if degree day projections suggest a delivery is needed, the system will wait until the minimum interval passes.

5. Set trigger thresholds

Define when to dispatch:

Example scenario

Degree day accumulation (simplified):

Degree day data sources

Your system may automatically pull degree day data but at any time you can update or modify it.

Improving accuracy

We Recompute K-factor regularly

Adjust for customer behavior

Combine with monitors

See: Monitoring Guide

Troubleshooting common issues

Projections are too conservative (deliveries too frequent)

Projections are too aggressive (customer runs out)

Degree days don't match consumption

Sudden change in usage

Delivery Strategies

Understanding Fuel Monitoring

Tank monitoring systems use IoT devices to track fuel levels in real time. This guide explains how to link monitors to equipment, view monitor data in the app (Systems carousel), and use monitor data for delivery scheduling.

What is tank monitoring?

Tank monitoring devices:

Where to see monitor info in the app

You can quickly see monitor information from the customer dashboard:

When a system is linked to a tank monitor, the selector shows:

Tip: You can toggle the date/time display per system to reveal window start/end and target dates.

How the selector computes gallons remaining

The system selector calculates gallons remaining using the best available data:

  1. If a monitor reading is available

    • Uses the monitor's current level (e.g., 0.42 for 42%)
    • Multiplies by the system's recommended delivery capacity
    • Formula: gallons = monitorLevel * recommendedCapacity

  2. If no monitor reading is available (fallback)

    • Estimates consumption using degree days since the last full delivery
    • Applies seasonal usage rates (winter/summer) across the heating year
    • Subtracts estimated consumption from recommended capacity to estimate remaining gallons

This mirrors the in-app logic: monitor values take precedence; otherwise, the degree-day model provides a reasonable estimate.

Linking a monitor to a tank

  1. Navigate to Systems from the Customer Dashboard.
  2. Select the system and find the tank equipment.
  3. Click Edit on the tank.
  4. In the Monitoring section:
    • Monitor Link: Select or add the monitor
    • Monitor ID / Serial: Device serial number or identifier (required for monitored strategy)
    • Monitor Type: Float gauge, ultrasonic, pressure sensor, etc.
    • Vendor: Tank monitor vendor/brand
  5. Save the equipment.

The monitor is now linked and data will flow into the system and the Systems carousel.

Using monitor data for scheduling

To have the system automatically trigger deliveries based on monitor readings:

  1. Edit the system (Add/Edit System dialog)
  2. Set Window Strategy to Monitored
  3. Enter the Monitor Serial Number (required)
  4. Enable the Auto Delivery toggle

See: Window Strategies

Combining monitors with other strategies

Monitoring works best alongside other estimation methods:

Monitored (primary) + Degree Day (fallback)

Calendar + Monitor (validation)

For configuring priorities, see: Window Strategies

Monitor data fields

Real-time readings

Historical data

Offline behavior and stale readings

Monitors can go offline due to signal loss, power failure, or damage. Configure fallback behavior:

Stale reading grace period

Status indicators (implementation-dependent)

Calibration and accuracy

Initial calibration

When installing a monitor:

  1. Fill the tank to a known level (e.g., 100% after delivery)
  2. Calibrate the monitor to read that level accurately
  3. Verify readings against gauge or stick measurements for a few weeks

Ongoing calibration

This can be done with the rate checking feature on the fuel deliveries page Fuel Deliveries

Common accuracy issues

Troubleshooting from the Systems carousel

Delivery Strategies

Creating a Calendar Schedule

Calendar Scheduling Guide

Calendar scheduling creates time-based recurring delivery requests based on configured rules. This guide explains how to set up, manage, and use calendar schedules within the system dialog.

What is calendar scheduling?

Calendar scheduling automatically generates delivery requests based on:

Calendar schedules are configured in the Calendar Schedules tab of the Add/Edit System dialog.

When to use calendar scheduling

Use calendar scheduling for:

Accessing calendar schedules

Calendar schedules are managed in the System dialog:

  1. Navigate to Systems from the Customer Dashboard
  2. Click Add System (for new) or Edit on an existing system
  3. Select the Calendar Schedules tab
  4. You'll see an info message: "Calendar schedules automatically create delivery requests based on recurring rules. Only one schedule can be active at a time."

Important: For new systems, you must save the system first before you can add calendar schedules. You'll see a warning: "Save the system before managing calendar schedules."

Creating a calendar schedule

Step 1: Click "Add Schedule"

After saving the system, click the Add Schedule button to open the schedule form.

Step 2: Configure frequency

The form has three frequency fields in the first row:

Frequency (number)

Units (dropdown)

Preferred Day of Week (dropdown, optional)

Example combinations:

Step 3: Set seasonal dates (optional)

Season Starts and Season Ends

Example:

Step 4: Set delivery volume (optional)

Requested Volume (gal)

Step 5: Set active status

Active toggle

Step 6: Save the schedule

Click Create Schedule (or Update Schedule if editing).

The schedule will appear in the list below with:

Managing existing schedules

Each schedule in the list displays:

Header:

Details:

Action buttons:

Schedule states and rules

Only one active schedule

The system enforces that only one calendar schedule can be active at a time per system:

Inactive schedules

Inactive schedules:

Loading and error states

Example configurations

Example 1: Biweekly residential delivery

Configuration:

Result: Delivers 200 gallons every 2 weeks on Tuesday, year-round

Example 2: Monthly commercial fill

Configuration:

Result: Monthly delivery on any day with automatic volume calculation

Example 3: Seasonal heating oil

Configuration:

Result: Delivery every 3 weeks during heating season only (Oct 1 – Apr 30)

Editing a schedule

  1. Click Edit on the schedule you want to modify
  2. The schedule form appears with current values populated
  3. Make your changes
  4. Click Update Schedule to save
  5. The schedule list updates with the new configuration

You can change any field: frequency, units, day of week, seasonal dates, volume, or active status.

Switching between schedules

To switch from one schedule to another (e.g., winter to summer):

  1. Create both schedules with appropriate settings
  2. Set one as Active (this becomes the current schedule)
  3. When the season changes, click Set Active on the other schedule
  4. The system automatically deactivates the previous schedule and activates the new one

Example:

Deleting a schedule

Click Delete on a schedule to remove it permanently. This action typically requires confirmation and cannot be undone.

Caution: Deleting an active schedule stops automatic delivery generation. Ensure you have another schedule activated or switch the system to a different window strategy.

Calendar schedules and window strategies

Calendar scheduling is selected as a Window Strategy at the system level:

  1. In the system dialog, set Window Strategy to Calendar
  2. Enable Auto Delivery toggle if you want automatic delivery request generation
  3. Configure your calendar schedule(s) in the Calendar Schedules tab

With Auto Delivery enabled and an active calendar schedule, the system will automatically generate delivery requests based on the configured frequency and rules.

See: Window Strategies

Combining calendar with other data

Calendar + Monitor validation

If the system also has a tank monitor:

Calendar + Degree Day cross-check

If degree day settings are also configured:

Troubleshooting

Cannot add schedules

Issue: "Save the system before managing calendar schedules" warning appears Solution: Click Submit on the system dialog to save the system first, then edit it again to add schedules

Schedule not generating deliveries

Issue: Schedule is created but deliveries aren't happening Check:

Wrong delivery frequency

Issue: Deliveries happening too often or too infrequently Solution: Edit the schedule and adjust Frequency/Units to match desired cadence

All schedules become inactive

Issue: Activating a schedule deactivates all others Expected behavior: This is by design. Only one schedule can be active at a time.