Resource Period Rules

Period rules enforce time-based constraints on resources over extended periods, ensuring compliance with labor laws, safety regulations, and operational policies. This guide covers daily, weekly, and monthly limits for work time, drive time, and service time.

Period Rule Configuration

Define rules within each resource:

{
  "resources": [
    {
      "id": "driver-1",
      "name": "Driver 1",
      "periodRules": [
        {
          "type": "MAX_DRIVE_TIME",
          "period": "DAY",
          "value": 32400  // 9 hours max driving per day
        },
        {
          "type": "MAX_WORK_TIME",
          "period": "WEEK", 
          "value": 216000  // 60 hours max per week
        }
      ],
      "shifts": [
        {
          "id": "shift1",
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    }
  ],
  "jobs": [
    {
      "id": "job1",
      "name": "Example Job"
    }
  ]
}

Rule Types

Work Time Rules

Total time from shift start to end:

{
  "type": "MAX_WORK_TIME",
  "period": "DAY",
  "value": 36000  // 10 hours
}

Includes breaks and waiting time

Drive Time Rules

Actual time spent driving/traveling:

{
  "periodRules": [
    {
      "type": "MAX_DRIVE_TIME",
      "period": "DAY",
      "value": 32400  // 9 hours daily limit
    },
    {
      "type": "MAX_DRIVE_TIME", 
      "period": "WEEK",
      "value": 162000  // 45 hours weekly limit
    }
  ]
}

Service Time Rules

Productive time at job locations:

{
  "type": "MAX_SERVICE_TIME",
  "period": "DAY",
  "value": 28800  // 8 hours max
}

Service Time = Time spent performing jobs (excludes travel and breaks)

Period Types

DAY Period

Rolling 24-hour window from current time:

Calculation

Looks back 24 hours from job start time

Example

Job at 14:00 on Tuesday checks work from 14:00 Monday

Use Case

Daily driving limits, fatigue management

WEEK Period

Rolling 7-day window:

Calculation

Looks back 168 hours (7 × 24) from job start

Example

Job on Friday checks total work since previous Friday

Use Case

Weekly hour limits, EU drivers’ hours rules

MONTH Period

Rolling 30-day window:

Calculation

Looks back 720 hours (30 × 24) from job start

Example

Job on March 15 checks work since February 13

Use Case

Monthly quotas, long-term fatigue management

Legal Compliance Examples

EU Drivers’ Hours

{
  "resources": [{
    "id": "eu-driver",
    "name": "EU Driver",
    "periodRules": [
      // Daily driving limit
      {
        "type": "MAX_DRIVE_TIME",
        "period": "DAY",
        "value": 32400  // 9 hours (can be extended to 10 twice a week)
      },
      // Weekly driving limit
      {
        "type": "MAX_DRIVE_TIME",
        "period": "WEEK",
        "value": 201600  // 56 hours
      },
      // Bi-weekly driving limit (approximated with month)
      {
        "type": "MAX_DRIVE_TIME",
        "period": "MONTH",
        "value": 324000  // 90 hours per 2 weeks
      },
      // Daily rest requirement (inverse of work time)
      {
        "type": "MAX_WORK_TIME",
        "period": "DAY",
        "value": 46800  // 13 hours max work (11 hours rest)
      }
    ],
    "shifts": [
      {
        "id": "shift1",
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }
    ]
  }],
  "jobs": [
    {
      "id": "job1",
      "name": "Example Job"
    }
  ]
}

US DOT Hours of Service

{
  "resources": [{
    "id": "us-driver",
    "name": "US Driver",
    "periodRules": [
      // 11-hour driving limit
      {
        "type": "MAX_DRIVE_TIME",
        "period": "DAY",
        "value": 39600  // 11 hours
      },
      // 14-hour on-duty limit
      {
        "type": "MAX_WORK_TIME",
        "period": "DAY",
        "value": 50400  // 14 hours
      },
      // 60-hour/7-day limit
      {
        "type": "MAX_WORK_TIME",
        "period": "WEEK",
        "value": 216000  // 60 hours
      },
      // 70-hour/8-day limit (approximated)
      {
        "type": "MAX_WORK_TIME",
        "period": "WEEK",
        "value": 252000,  // 70 hours
        "rollingDays": 8  // Custom period
      }
    ],
    "shifts": [
      {
        "id": "shift1",
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }
    ]
  }],
  "jobs": [
    {
      "id": "job1",
      "name": "Example Job"
    }
  ]
}

Soft vs Hard Enforcement

Hard Limits (Default)

Jobs cannot be assigned if they would violate rules:

{
  "periodRules": [{
    "type": "MAX_DRIVE_TIME",
    "period": "DAY",
    "value": 32400,
    "hard": true  // Default
  }]
}

Soft Limits

Allow violations with penalties:

{
  "periodRules": [{
    "type": "MAX_SERVICE_TIME",
    "period": "DAY",
    "value": 28800,
    "hard": false,
    "weight": 100  // Penalty per minute over limit
  }],
  "options": {
    "weights": {
      "periodRuleViolationWeight": 1.0
    }
  }
}

Complex Scenarios

Multi-Role Resources

Different rules for different activities:

{
  "resources": [{
    "id": "driver-installer",
    "name": "Driver Installer",
    "tags": [
      {"name": "driver", "hard": true},
      {"name": "installer", "hard": true}
    ],
    "periodRules": [
      // Driving limits
      {
        "type": "MAX_DRIVE_TIME",
        "period": "DAY",
        "value": 28800,  // 8 hours driving
        "tags": ["driver"]
      },
      // Installation limits
      {
        "type": "MAX_SERVICE_TIME",
        "period": "DAY",
        "value": 21600,  // 6 hours installing
        "tags": ["installer"]
      },
      // Overall work limit
      {
        "type": "MAX_WORK_TIME",
        "period": "DAY",
        "value": 36000  // 10 hours total
      }
    ],
    "shifts": [
      {
        "id": "shift1",
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }
    ]
  }],
  "jobs": [
    {
      "id": "job1",
      "name": "Example Job"
    }
  ]
}

Quota Management

Minimum service requirements:

{
  "resources": [{
    "id": "sales-rep",
    "name": "Sales Representative",
    "periodRules": [
      // Daily minimum visits
      {
        "type": "MIN_SERVICE_TIME",
        "period": "DAY",
        "value": 18000  // 5 hours customer time
      },
      // Weekly minimum
      {
        "type": "MIN_SERVICE_TIME",
        "period": "WEEK",
        "value": 108000  // 30 hours per week
      },
      // Don't overwork
      {
        "type": "MAX_WORK_TIME",
        "period": "DAY",
        "value": 36000  // 10 hours max
      }
    ],
    "shifts": [
      {
        "id": "shift1",
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }
    ]
  }],
  "jobs": [
    {
      "id": "job1",
      "name": "Example Job"
    }
  ]
}

Monitoring and Reporting

Period Rule Status

Track rule compliance in solutions:

{
  "resourceStats": {
    "driver-1": {
      "periodRuleStatus": [
        {
          "rule": "MAX_DRIVE_TIME_DAY",
          "used": 28800,    // 8 hours used
          "limit": 32400,   // 9 hours allowed
          "remaining": 3600, // 1 hour remaining
          "utilization": 0.89
        },
        {
          "rule": "MAX_WORK_TIME_WEEK", 
          "used": 180000,   // 50 hours used
          "limit": 216000,  // 60 hours allowed
          "remaining": 36000, // 10 hours remaining
          "utilization": 0.83
        }
      ]
    }
  }
}

Best Practices

Start Conservative

Set limits slightly below legal requirements for buffer

Consider Patterns

Account for typical work patterns and peak periods

Use Multiple Rules

Combine daily and weekly limits for comprehensive control

Monitor Utilization

Track how close resources get to limits

Plan Ahead

Consider future shifts when near limits

Troubleshooting

Jobs Not Assigned Due to Period Rules

Symptoms: Unassigned jobs with “PERIOD_RULE_VIOLATION” reasonCheck:

Current period usage for resources
Rule values vs job requirements
Hard vs soft rule configuration

Solutions:

Add more resources
Adjust shift patterns
Convert to soft rules if appropriate

Unexpected Rule Violations

Symptoms: Rules violated despite seeming availabilityCheck:

Rolling window calculations
Previous days’ work history
All active rules for resource

Solutions:

Verify historical data
Check period window logic
Review rule combinations

Performance Impact

Symptoms: Slow solving with period rulesCheck:

Number of rules per resource
Historical data lookup time
Complex rule combinations

Solutions:

Limit rules to necessary ones
Use appropriate period types
Consider caching historical data

Configuration Examples

Fatigue Management

{
  "periodRules": [
    // Prevent excessive daily work
    {
      "type": "MAX_WORK_TIME",
      "period": "DAY",
      "value": 43200  // 12 hours
    },
    // Ensure adequate weekly rest
    {
      "type": "MAX_WORK_TIME",
      "period": "WEEK", 
      "value": 216000  // 60 hours
    },
    // Prevent continuous long days
    {
      "type": "MAX_DRIVE_TIME",
      "period": "DAY",
      "value": 32400,  // 9 hours
      "consecutiveDayLimit": 2  // Only 2 long days in a row
    }
  ]
}

Productivity Targets

{
  "periodRules": [
    // Minimum daily productivity
    {
      "type": "MIN_SERVICE_TIME",
      "period": "DAY",
      "value": 21600,  // 6 hours
      "hard": false,
      "weight": 50
    },
    // Weekly targets
    {
      "type": "MIN_SERVICE_TIME",
      "period": "WEEK",
      "value": 126000,  // 35 hours
      "hard": false,
      "weight": 100
    }
  ]
}

Resource Management

Basic resource configuration

Break Management

Daily break requirements

Advanced Constraints

Other resource constraints

Time Scheduling

Multi-day shift patterns

Platform

VRP API

Resource Period Rules

Resource Period Rules

Period Rule Configuration

Rule Types

Work Time Rules

Drive Time Rules

Service Time Rules

Period Types

DAY Period

WEEK Period

MONTH Period

Legal Compliance Examples

EU Drivers’ Hours

US DOT Hours of Service

Soft vs Hard Enforcement

Hard Limits (Default)

Soft Limits

Complex Scenarios

Multi-Role Resources

Quota Management

Monitoring and Reporting

Period Rule Status

Best Practices

Troubleshooting

Configuration Examples

Fatigue Management

Productivity Targets

Resource Management

Break Management

Advanced Constraints

Time Scheduling

Platform

VRP API

​Resource Period Rules

​Period Rule Configuration

​Rule Types

​Work Time Rules

​Drive Time Rules

​Service Time Rules

​Period Types

​DAY Period

​WEEK Period

​MONTH Period

​Legal Compliance Examples

​EU Drivers’ Hours

​US DOT Hours of Service

​Soft vs Hard Enforcement

​Hard Limits (Default)

​Soft Limits

​Complex Scenarios

​Multi-Role Resources

​Quota Management

​Monitoring and Reporting

​Period Rule Status

​Best Practices

​Troubleshooting

​Configuration Examples

​Fatigue Management

​Productivity Targets

​Related Features

Resource Management

Break Management

Advanced Constraints

Time Scheduling

Resource Period Rules

Period Rule Configuration

Rule Types

Work Time Rules

Drive Time Rules

Service Time Rules

Period Types

DAY Period

WEEK Period

MONTH Period

Legal Compliance Examples

EU Drivers’ Hours

US DOT Hours of Service

Soft vs Hard Enforcement

Hard Limits (Default)

Soft Limits

Complex Scenarios

Multi-Role Resources

Quota Management

Monitoring and Reporting

Period Rule Status

Best Practices

Troubleshooting

Configuration Examples

Fatigue Management

Productivity Targets

Related Features