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": [
    {
      "name": "Driver 1",
      "shifts": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    }
  ],
  "jobs": [
    {
      "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[string]

Skills, certifications, or capabilities, as plain tag names

Location

Preferred geographic point for this resource, a soft preference

Multi-Shift Resources

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

{
  "resources": [
    {
      "name": "Flexible Driver",
      "shifts": [
        {
          "from": "2024-03-15T06:00:00Z",
          "to": "2024-03-15T10:00:00Z",
          "start": {"latitude": 52.520, "longitude": 13.405},
          "end": {"latitude": 52.520, "longitude": 13.405}
        },
        {
          "from": "2024-03-15T14:00:00Z",
          "to": "2024-03-15T18:00:00Z",
          "start": {"latitude": 52.520, "longitude": 13.405},
          "end": {"latitude": 52.525, "longitude": 13.410}
        },
        {
          "from": "2024-03-16T08:00:00Z",
          "to": "2024-03-16T17:00:00Z",
          "start": {"latitude": 52.525, "longitude": 13.410},
          "end": {"latitude": 52.520, "longitude": 13.405}
        }
      ]
    }
  ],
  "jobs": [
    {
      "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

Location

Ending location for this shift

datetime

Latest possible end time when overtime is allowed (see weights.overtimeWeight)

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": [
    {
      "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": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    }
  ],
  "jobs": [
    {
      "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 (optional {from, to}; omit it and the rule covers the whole planning period), 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 the request-level weights.periodRuleWeight.

Workload Balancing

Distribute work fairly across resources:

Fair Workload Per Resource

Spread each resource’s own workload evenly across its available days. fairWorkloadPerResource is a boolean in options; the strength comes from the top-level weights.workloadSpreadWeight:

{
  "options": {
    "fairWorkloadPerResource": true
  },
  "weights": {
    "workloadSpreadWeight": 50
  }
}

Higher workloadSpreadWeight values make the solver push harder for an even distribution. options.workloadSensitivity also influences the effect.

Fair Workload Per Trip

Spread service time across all resources and all days/trips:

{
  "options": {
    "fairWorkloadPerTrip": true
  },
  "weights": {
    "workloadSpreadWeight": 30
  }
}

Geographic Restrictions

Resource Region

A resource’s region is a single location (latitude/longitude), not a named area. It is a soft preference for keeping that resource working near that point. Its strength is set by weights.regionMinimisationWeight. Jobs have no region field; their position comes from location.

{
  "resources": [
    {
      "name": "North Team",
      "region": {"latitude": 52.540, "longitude": 13.420},
      "shifts": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    },
    {
      "name": "South Team",
      "region": {"latitude": 52.480, "longitude": 13.380},
      "shifts": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    }
  ],
  "jobs": [
    {
      "name": "Delivery 1",
      "location": {"latitude": 52.520, "longitude": 13.405}
    }
  ],
  "weights": {
    "regionMinimisationWeight": 10
  }
}

Distance-Based Restrictions

Limit how far a resource drives with maxDriveDistance (meters, on the resource):

{
  "resources": [
    {
      "name": "Local Driver",
      "maxDriveDistance": 50000,  // 50 km of driving
      "shifts": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    }
  ],
  "jobs": [
    {
      "name": "Example Job"
    }
  ]
}

Skill and Tag Management

Match resource capabilities with job requirements:

{
  "resources": [
    {
      "name": "Certified Technician",
      "tags": ["electrical", "plumbing", "senior"],
      "shifts": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    }
  ],
  "jobs": [
    {
      "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 that list that tag in their tags can be assigned

Soft Tags Preferred

Soft tags ("hard": false on the job tag) create preference but aren’t required

Weight Controls Strength

A higher weight on a soft job tag makes that preference stronger

Preferred Resources

Allow soft preferences for specific resource assignments with job rankings (1 is most preferred, 100 least). Set weights.rankingWeight above 0 so rankings influence the plan:

{
  "resources": [
    {
      "name": "Senior Technician 1",
      "shifts": [{"from": "2024-03-15T08:00:00Z", "to": "2024-03-15T17:00:00Z"}]
    },
    {
      "name": "Senior Technician 2",
      "shifts": [{"from": "2024-03-15T08:00:00Z", "to": "2024-03-15T17:00:00Z"}]
    }
  ],
  "jobs": [
    {
      "name": "VIP Customer Service",
      "rankings": [
        {"name": "Senior Technician 1", "ranking": 1},
        {"name": "Senior Technician 2", "ranking": 5}
      ]
    }
  ],
  "weights": {
    "rankingWeight": 100
  }
}

See Tag & Ranking System for the ranking scale.

Complex Example: Field Service Team

Here’s a comprehensive example combining multiple resource features:

{
  "resources": [
    {
      "name": "Senior Technician North",
      "tags": ["electrical", "plumbing", "senior"],
      "region": {"latitude": 52.540, "longitude": 13.420},
      "capacity": [50],  // Tool weight limit
      "shifts": [
        {
          "from": "2024-03-15T07:00:00Z",
          "to": "2024-03-15T12:00:00Z",
          "start": {"latitude": 52.540, "longitude": 13.420},
          "end": {"latitude": 52.540, "longitude": 13.420}
        },
        {
          "from": "2024-03-15T13:00:00Z",
          "to": "2024-03-15T17:00:00Z",
          "start": {"latitude": 52.540, "longitude": 13.420},
          "end": {"latitude": 52.540, "longitude": 13.420},
          "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
        }
      ]
    },
    {
      "name": "Junior Technician South",
      "tags": ["electrical", "junior"],
      "region": {"latitude": 52.480, "longitude": 13.380},
      "capacity": [30],
      "shifts": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z",
          "start": {"latitude": 52.540, "longitude": 13.420},
          "end": {"latitude": 52.540, "longitude": 13.420},
          "breaks": [
            {
              "type": "WINDOWED",
              "duration": 3600,
              "from": "2024-03-15T12:00:00Z",
              "to": "2024-03-15T13:00:00Z"
            }
          ]
        }
      ]
    },
    {
      "name": "Flexible Contractor",
      "tags": ["electrical", "contractor"],
      "capacity": [40],
      "shifts": [
        {
          "from": "2024-03-15T10:00:00Z",
          "to": "2024-03-15T18:00:00Z"
        }
      ],
      "hourlyCost": 75  // Higher cost for contractors
    }
  ],
  "jobs": [
    {
      "name": "Example Job"
    }
  ],
  "options": {
    "fairWorkloadPerResource": true
  },
  "weights": {
    "workloadSpreadWeight": 50,
    "rankingWeight": 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 = increased matching complexity

Recommendations:

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 weights.rankingWeight and check the job rankings
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 weights.workloadSpreadWeight (with options.fairWorkloadPerResource or options.fairWorkloadPerTrip set to true)
Adjust shift patterns for better coverage
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

Resource Region

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

​Resource Region

​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

Resource Region

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