Resource Management

Resources represent the vehicles, drivers, or teams that execute your routes. This guide covers advanced resource configuration including multi-shift scheduling, workload balancing, period constraints, and geographic restrictions.

Basic Resource Configuration

Every resource requires at minimum a name and shift definition:

{
  "resources": [
    {
      "id": "driver-1",
      "name": "Driver 1",
      "shifts": [
        {
          "id": "shift1",
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    }
  ],
  "jobs": [
    {
      "id": "job1",
      "name": "Example Job"
    }
  ]
}

Essential Resource Properties

string

required

Unique identifier for the resource

array

required

Working periods when the resource is available

array[integer]

Loading capacity in multiple dimensions (e.g., [weight, volume])

array[Tag]

Skills, certifications, or capabilities

array[string]

Geographic areas where resource can operate

Multi-Shift Resources

Resources can work multiple shifts per day or across different days:

{
  "resources": [
    {
      "id": "driver-flexible",
      "name": "Flexible Driver",
      "shifts": [
        {
          "id": "shift1",
          "start": {
            "location": {"lat": 52.520, "lon": 13.405},
            "time": "2024-03-15T06:00:00Z"
          },
          "end": {
            "location": {"lat": 52.520, "lon": 13.405},
            "time": "2024-03-15T10:00:00Z"
          }
        },
        {
          "id": "shift2",
          "start": {
            "location": {"lat": 52.520, "lon": 13.405},
            "time": "2024-03-15T14:00:00Z"
          },
          "end": {
            "location": {"lat": 52.525, "lon": 13.410},
            "time": "2024-03-15T18:00:00Z"
          }
        },
        {
          "id": "shift3",
          "start": {
            "location": {"lat": 52.525, "lon": 13.410},
            "time": "2024-03-16T08:00:00Z"
          },
          "end": {
            "location": {"lat": 52.520, "lon": 13.405},
            "time": "2024-03-16T17:00:00Z"
          }
        }
      ]
    }
  ],
  "jobs": [
    {
      "id": "job1",
      "name": "Example Job"
    }
  ]
}

Each shift can have different start/end locations. This is useful for drivers who:

Start from home in the morning
End at a depot
Continue from previous day’s end location

Shift Properties

datetime

required

Shift start time (ISO 8601 format)

datetime

required

Shift end time

Location

Starting location for this shift (defaults to first job location)

Location

Ending location for this shift (defaults to last job location)

datetime

Latest possible end time with overtime penalty

array[Break]

Scheduled breaks during the shift

Period Constraints

Control resource utilization over explicit time windows using the rules array. Each rule pairs a period (an explicit from/to date-time window — there is no "DAY"/"WEEK"/"MONTH" keyword) with one or more direct limit fields:

{
  "resources": [
    {
      "id": "driver-1",
      "name": "Driver 1",
      "rules": [
        {
          "period": { "from": "2024-03-15T00:00:00Z", "to": "2024-03-16T00:00:00Z" },
          "maxWorkTime": 28800,   // 8 hours max that day
          "minServiceTime": 14400 // Minimum 4 hours productive work that day
        },
        {
          "period": { "from": "2024-03-11T00:00:00Z", "to": "2024-03-18T00:00:00Z" },
          "maxDriveTime": 144000  // 40 hours max that week
        }
      ],
      "shifts": [
        {
          "id": "shift1",
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    }
  ],
  "jobs": [
    {
      "id": "job1",
      "name": "Example Job"
    }
  ]
}

There is no rolling DAY/WEEK/MONTH period shorthand. To cap a resource per day and per week, declare one rule per day (its period spanning that specific day) plus one rule spanning the whole week — each with an explicit from/to.

Available Rule Fields

Work Time Limits
Drive Time Limits
Service Time Requirements

{
  "period": { "from": "2024-03-15T00:00:00Z", "to": "2024-03-16T00:00:00Z" },
  "maxWorkTime": 32400  // 9 hours
}

maxWorkTime/minWorkTime: service time + drive time within the period

{
  "period": { "from": "2024-03-11T00:00:00Z", "to": "2024-03-18T00:00:00Z" },
  "maxDriveTime": 144000  // 40 hours
}

maxDriveTime/minDriveTime: actual driving/travel time only

{
  "period": { "from": "2024-03-15T00:00:00Z", "to": "2024-03-16T00:00:00Z" },
  "minServiceTime": 21600  // 6 hours minimum
}

maxServiceTime/minServiceTime: productive time spent at job locations

Full field list on a rule: period (required, {from, to}), minWorkTime/maxWorkTime, minServiceTime/maxServiceTime, minDriveTime/maxDriveTime, minJobComplexity/maxJobComplexity, jobTypeLimitations (map of job type to max count), groupTag (see Resource Period Rules for pooling). max* violations are enforced as hard constraints; min* violations are penalized as medium-tier (utilization) constraints — both scaled by options.weights.periodRuleWeight.

Workload Balancing

Distribute work fairly across resources:

Fair Workload Per Resource

Balance total work time across all resources:

{
  "options": {
    "weights": {
      "fairWorkloadPerResource": 50
    }
  }
}

How it works:

Calculates average workload across all resources
Penalizes deviations from the average
Higher weight = stronger preference for balance

// With fairWorkloadPerResource: 100
{
  "resource1": "6 hours work",
  "resource2": "6.5 hours work",
  "resource3": "5.5 hours work"
}

// With fairWorkloadPerResource: 0
{
  "resource1": "9 hours work",
  "resource2": "3 hours work",
  "resource3": "4 hours work"
}

Fair Workload Per Trip

Balance work within individual trips/routes:

{
  "options": {
    "weights": {
      "fairWorkloadPerTrip": 30
    }
  }
}

Use cases:

Ensure lunch breaks fall at reasonable times
Prevent very short or very long individual routes
Balance morning vs afternoon workloads

Geographic Restrictions

Region-Based Assignment

Limit resources to specific geographic areas:

{
  "resources": [
    {
      "id": "north-team",
      "name": "North Team",
      "regions": ["region-north", "region-central"],
      "shifts": [
        {
          "id": "shift1",
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    },
    {
      "id": "south-team",
      "name": "South Team", 
      "regions": ["region-south", "region-central"],
      "shifts": [
        {
          "id": "shift1",
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    }
  ],
  "jobs": [
    {
      "id": "delivery-1",
      "name": "Delivery 1",
      "location": {"lat": 52.520, "lon": 13.405},
      "region": "region-north"
    }
  ]
}

Jobs with regions can ONLY be assigned to resources that include that region in their regions list.

Distance-Based Restrictions

Limit how far resources travel from their base:

{
  "resources": [
    {
      "id": "local-driver",
      "name": "Local Driver",
      "shifts": [{
        "id": "shift1",
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z",
        "maxDistance": 50000  // 50km radius from start
      }]
    }
  ],
  "jobs": [
    {
      "id": "job1",
      "name": "Example Job"
    }
  ]
}

Skill and Tag Management

Match resource capabilities with job requirements:

{
  "resources": [
    {
      "id": "certified-technician",
      "name": "Certified Technician",
      "tags": [
        {"name": "electrical", "hard": true},
        {"name": "plumbing", "hard": true},
        {"name": "senior", "hard": false}
      ],
      "shifts": [
        {
          "id": "shift1",
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    }
  ],
  "jobs": [
    {
      "id": "electrical-repair",
      "name": "Electrical Repair",
      "tags": [
        {"name": "electrical", "hard": true}  // Must match
      ]
    }
  ]
}

Tag Matching Rules

Hard Tags Must Match

If a job has a hard tag, only resources with that tag can be assigned

Soft Tags Preferred

Soft tags create preference but aren’t required

Weight Controls Strength

Higher weight values make soft preferences stronger

Preferred Resources

Allow soft preferences for specific resource assignments:

{
  "resources": [
    {
      "id": "senior-tech-1",
      "name": "Senior Technician 1",
      "shifts": [{"id": "shift1", "from": "2024-03-15T08:00:00Z", "to": "2024-03-15T17:00:00Z"}]
    },
    {
      "id": "senior-tech-2",
      "name": "Senior Technician 2",
      "shifts": [{"id": "shift1", "from": "2024-03-15T08:00:00Z", "to": "2024-03-15T17:00:00Z"}]
    }
  ],
  "jobs": [
    {
      "id": "vip-customer-service",
      "name": "VIP Customer Service",
      "preferredResources": ["senior-tech-1", "senior-tech-2"],
      "allowedResources": ["senior-tech-1", "senior-tech-2", "tech-3", "tech-4"]
    }
  ],
  "options": {
    "weights": {
      "preferredResourceWeight": 100
    }
  }
}

Resource Assignment Priority:

allowedResources - Hard constraint (if specified)
preferredResources - Soft preference with penalty
Tag matching - Based on hard/soft tags
General pool - Any available resource

Complex Example: Field Service Team

Here’s a comprehensive example combining multiple resource features:

{
  "resources": [
    {
      "id": "senior-tech-north",
      "name": "Senior Technician North",
      "category": "TECHNICIAN",
      "tags": [
        {"name": "electrical", "hard": true},
        {"name": "plumbing", "hard": true},
        {"name": "senior", "hard": true}
      ],
      "regions": ["north", "central"],
      "capacity": [50],  // Tool weight limit
      "shifts": [
        {
          "id": "morning-shift",
          "start": {
            "location": {"lat": 52.540, "lon": 13.420},
            "time": "2024-03-15T07:00:00Z"
          },
          "end": {
            "location": {"lat": 52.540, "lon": 13.420},
            "time": "2024-03-15T12:00:00Z"
          }
        },
        {
          "id": "afternoon-shift",
          "start": {
            "location": {"lat": 52.540, "lon": 13.420},
            "time": "2024-03-15T13:00:00Z"
          },
          "end": {
            "location": {"lat": 52.540, "lon": 13.420},
            "time": "2024-03-15T17:00:00Z"
          },
          "overtimeEnd": "2024-03-15T19:00:00Z"
        }
      ],
      "rules": [
        {
          "period": { "from": "2024-03-15T00:00:00Z", "to": "2024-03-16T00:00:00Z" },
          "maxWorkTime": 36000  // 10 hours max that day
        },
        {
          "period": { "from": "2024-03-11T00:00:00Z", "to": "2024-03-18T00:00:00Z" },
          "maxDriveTime": 108000  // 30 hours driving that week
        }
      ]
    },
    {
      "id": "junior-tech-south",
      "name": "Junior Technician South",
      "category": "TECHNICIAN",
      "tags": [
        {"name": "electrical", "hard": true},
        {"name": "junior", "hard": true}
      ],
      "regions": ["south", "central"],
      "capacity": [30],
      "shifts": [
        {
          "id": "full-day",
          "start": {
            "location": {"lat": 52.540, "lon": 13.420},
            "time": "2024-03-15T08:00:00Z"
          },
          "end": {
            "location": {"lat": 52.540, "lon": 13.420},
            "time": "2024-03-15T17:00:00Z"
          },
          "breaks": [
            {
              "type": "FIXED",
              "from": "2024-03-15T12:00:00Z",
              "to": "2024-03-15T13:00:00Z"
            }
          ]
        }
      ]
    },
    {
      "id": "contractor-flex",
      "name": "Flexible Contractor",
      "category": "CONTRACTOR",
      "tags": [
        {"name": "electrical", "hard": true},
        {"name": "contractor", "hard": true}
      ],
      "regions": ["north", "south", "central"],
      "capacity": [40],
      "shifts": [
        {
          "id": "contractor-shift",
          "from": "2024-03-15T10:00:00Z",
          "to": "2024-03-15T18:00:00Z"
        }
      ],
      "hourlyCost": 75  // Higher cost for contractors
    }
  ],
  "jobs": [
    {
      "id": "job1",
      "name": "Example Job"
    }
  ],
  "options": {
    "weights": {
      "fairWorkloadPerResource": 50,
      "preferredResourceWeight": 100,
      "overtimeWeight": 200
    }
  }
}

Performance Optimization

Resource Pool Size

Performance Impact of Resource Features:

More resources = more routing possibilities
Complex constraints = longer solve times
Many tags/regions = increased matching complexity

Recommendations:

Keep active resource pool under 100 for real-time solving
Use shift patterns to reduce combinations
Limit tag variations to necessary distinctions

Best Practices

Start Simple

Begin with basic resource definitions and add constraints incrementally

Use Appropriate Constraints

Hard constraints for legal/safety requirements
Soft constraints for preferences
Period rules for compliance

Test Resource Utilization

Monitor these metrics:

Average utilization per resource
Overtime frequency
Unassigned jobs due to resource constraints

Balance Flexibility and Control

Too many restrictions can make problems infeasible

Troubleshooting

Common Issues

Jobs Not Assigned to Preferred Resources

Possible Causes:

Preferred resource doesn’t have required tags
Resource shift doesn’t cover job time window
Capacity constraints prevent assignment
Travel time makes assignment inefficient

Solutions:

Verify resource has all required capabilities
Check shift coverage and time windows
Increase preferredResourceWeight
Review overall constraint interactions

Uneven Workload Distribution

Possible Causes:

Geographic clustering of jobs
Skill requirements limiting options
Time window constraints
Different shift lengths

Solutions:

Increase fairWorkloadPerResource weight
Adjust shift patterns for better coverage
Consider redistributing regions
Add more flexible resources

Period Constraints Violated

Possible Causes:

Constraints too restrictive
Not enough resources for workload
Poor shift distribution

Solutions:

Review and adjust period rule values
Add additional resources or shifts
Enable partial planning
Distribute work across more days

Time Scheduling

Detailed shift configuration and time management

Cost Optimization

Resource costs and optimization strategies

Tag System

Advanced tag matching and ranking

Break Management

Configure breaks within shifts

Platform

VRP API

Fill API

Resource Management

Resource Management

Basic Resource Configuration

Essential Resource Properties

Multi-Shift Resources

Shift Properties

Period Constraints

Available Rule Fields

Workload Balancing

Fair Workload Per Resource

Fair Workload Per Trip

Geographic Restrictions

Region-Based Assignment

Distance-Based Restrictions

Skill and Tag Management

Tag Matching Rules

Preferred Resources

Complex Example: Field Service Team

Performance Optimization

Resource Pool Size

Best Practices

Troubleshooting

Common Issues

Time Scheduling

Cost Optimization

Tag System

Break Management

​Resource Management

​Basic Resource Configuration

​Essential Resource Properties

​Multi-Shift Resources

​Shift Properties

​Period Constraints

​Available Rule Fields

​Workload Balancing

​Fair Workload Per Resource

​Fair Workload Per Trip

​Geographic Restrictions

​Region-Based Assignment

​Distance-Based Restrictions

​Skill and Tag Management

​Tag Matching Rules

​Preferred Resources

​Complex Example: Field Service Team

​Performance Optimization

​Resource Pool Size

​Best Practices

​Troubleshooting

​Common Issues

​Related Features

Time Scheduling

Cost Optimization

Tag System

Break Management

Resource Management

Basic Resource Configuration

Essential Resource Properties

Multi-Shift Resources

Shift Properties

Period Constraints

Available Rule Fields

Workload Balancing

Fair Workload Per Resource

Fair Workload Per Trip

Geographic Restrictions

Region-Based Assignment

Distance-Based Restrictions

Skill and Tag Management

Tag Matching Rules

Preferred Resources

Complex Example: Field Service Team

Performance Optimization

Resource Pool Size

Best Practices

Troubleshooting

Common Issues

Related Features