Resource Period Rules

Period rules enforce time-based constraints on resources over an explicit date-time window, ensuring compliance with labor laws, safety regulations, and operational policies. This guide covers work time, drive time, service time, and job-complexity limits.

There is no rolling DAY/WEEK/MONTH keyword. Every rule’s period is an explicit { "from", "to" } date-time range that you compute and pass in yourself — the solver does not derive “today” or “this week” on your behalf. To cap a resource per day and per week, declare one rule per day (each with its own period) plus one rule spanning the whole week.

Period Rule Configuration

Define rules within each resource, using the rules array (not periodRules):

{
  "resources": [
    {
      "id": "driver-1",
      "name": "Driver 1",
      "rules": [
        {
          "period": { "from": "2024-03-15T00:00:00Z", "to": "2024-03-16T00:00:00Z" },
          "maxDriveTime": 32400  // 9 hours max driving that day
        },
        {
          "period": { "from": "2024-03-11T00:00:00Z", "to": "2024-03-18T00:00:00Z" },
          "maxWorkTime": 216000  // 60 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"
    }
  ]
}

Rule Fields

Each entry in rules is a flat object — there is no type/value wrapper. Set whichever of these fields apply; any field left out means “no constraint” for that dimension.

Field	Description
`period`	Required. `{ "from": ISO-8601, "to": ISO-8601 }` — the explicit window the rule applies over.
`minWorkTime` / `maxWorkTime`	Work time (service + drive time) bounds, in seconds.
`minServiceTime` / `maxServiceTime`	Service time bounds, in seconds.
`minDriveTime` / `maxDriveTime`	Drive time bounds, in seconds.
`minJobComplexity` / `maxJobComplexity`	Bounds on the summed complexity of jobs completed.
`jobTypeLimitations`	Map of job type name to max count allowed in the period, e.g. `{"Install": 10}`.
`groupTag`	Optional pool identifier — see Pooled Rules below.

Work Time Rules

Work time is service time + drive time:

Daily Limit
Weekly Limit
Monthly Limit

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

{
  "period": { "from": "2024-03-11T00:00:00Z", "to": "2024-03-18T00:00:00Z" },
  "maxWorkTime": 216000  // 60 hours
}

{
  "period": { "from": "2024-03-01T00:00:00Z", "to": "2024-03-31T00:00:00Z" },
  "maxWorkTime": 720000  // 200 hours
}

Drive Time Rules

Actual time spent driving/traveling only:

{
  "rules": [
    {
      "period": { "from": "2024-03-15T00:00:00Z", "to": "2024-03-16T00:00:00Z" },
      "maxDriveTime": 32400  // 9 hours daily limit
    },
    {
      "period": { "from": "2024-03-11T00:00:00Z", "to": "2024-03-18T00:00:00Z" },
      "maxDriveTime": 162000  // 45 hours weekly limit
    }
  ]
}

Service Time Rules

Productive time at job locations:

{
  "period": { "from": "2024-03-15T00:00:00Z", "to": "2024-03-16T00:00:00Z" },
  "maxServiceTime": 28800  // 8 hours max
}

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

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

Building Daily, Weekly, and Monthly Windows

Since period is always an explicit window, “daily” and “weekly” limits are expressed by generating one rule per window client-side, not by a keyword:

Daily limit

For each calendar day the resource works, add one rule whose period.from/period.to span exactly that day (midnight to midnight, in the relevant time zone).

Weekly limit

Add one rule whose period spans the 7-day range you care about (a rolling week or a fixed calendar week — your choice, since you supply the exact bounds).

Monthly limit

Add one rule whose period spans the calendar (or rolling 30-day) range you care about.

A resource can declare any number of rules simultaneously — combine day-level and week-level rules on the same resource to get both limits at once (see the Period Rule Configuration example above).

Legal Compliance Examples

EU Drivers’ Hours

{
  "resources": [{
    "id": "eu-driver",
    "name": "EU Driver",
    "rules": [
      {
        "period": { "from": "2024-03-15T00:00:00Z", "to": "2024-03-16T00:00:00Z" },
        "maxDriveTime": 32400,  // 9 hours (can be extended to 10 twice a week)
        "maxWorkTime": 46800    // 13 hours max work (11 hours rest) that day
      },
      {
        "period": { "from": "2024-03-11T00:00:00Z", "to": "2024-03-18T00:00:00Z" },
        "maxDriveTime": 201600  // 56 hours that week
      }
    ],
    "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",
    "rules": [
      {
        "period": { "from": "2024-03-15T00:00:00Z", "to": "2024-03-16T00:00:00Z" },
        "maxDriveTime": 39600,  // 11-hour driving limit
        "maxWorkTime": 50400    // 14-hour on-duty limit
      },
      {
        "period": { "from": "2024-03-11T00:00:00Z", "to": "2024-03-18T00:00:00Z" },
        "maxWorkTime": 216000   // 60-hour/7-day limit
      }
    ],
    "shifts": [
      {
        "id": "shift1",
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }
    ]
  }],
  "jobs": [
    {
      "id": "job1",
      "name": "Example Job"
    }
  ]
}

An 8-day rolling window (e.g. the US 70-hour/8-day option) is just another explicit period — set from/to to span 8 days instead of 7.

Enforcement Tiers

Rules aren’t uniformly “hard” or “soft” — each bound has a fixed tier, and there is no per-rule hard/weight override:

max* fields (maxWorkTime, maxServiceTime, maxDriveTime, maxJobComplexity) are hard constraints. The solver will leave a job unassigned rather than push a resource over the limit, unless doing so is the only way to reach a feasible solution at all.
min* fields (minWorkTime, minServiceTime, minDriveTime, minJobComplexity) are medium-tier (utilization) constraints. They express a preference for keeping resources busy but will be traded off against other medium/soft objectives.
Both tiers are scaled by a single global weight, options.weights.periodRuleWeight (default 1), which multiplies the size of the violation — it does not change which tier a rule falls into.

{
  "options": {
    "weights": {
      "periodRuleWeight": 5
    }
  }
}

Complex Scenarios

Quota Management

Minimum service requirements alongside a maximum work-time ceiling:

{
  "resources": [{
    "id": "sales-rep",
    "name": "Sales Representative",
    "rules": [
      {
        "period": { "from": "2024-03-15T00:00:00Z", "to": "2024-03-16T00:00:00Z" },
        "minServiceTime": 18000,  // 5 hours customer time that day
        "maxWorkTime": 36000      // 10 hours max that day
      },
      {
        "period": { "from": "2024-03-11T00:00:00Z", "to": "2024-03-18T00:00:00Z" },
        "minServiceTime": 108000  // 30 hours per week
      }
    ],
    "shifts": [
      {
        "id": "shift1",
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }
    ]
  }],
  "jobs": [
    {
      "id": "job1",
      "name": "Example Job"
    }
  ]
}

Job-Type Quotas

Cap how many jobs of a given type a resource can complete in a period with jobTypeLimitations:

{
  "rules": [
    {
      "period": { "from": "2024-03-11T00:00:00Z", "to": "2024-03-18T00:00:00Z" },
      "jobTypeLimitations": { "Install": 10, "Wound Care": 5 }
    }
  ]
}

Pooled Rules (`groupTag`)

A period rule normally caps each declaring resource individually. Setting groupTag on a rule promotes it into a pool: the rule’s limits then apply collectively across every resource that declares an identical rule with the same groupTag. This is useful when a sub-group of resources needs a shared ceiling rather than per-resource caps — for example, “no more than 10 ‘Install’ jobs per week across all contractors combined”, regardless of how the work is divided among them.

{
  "resources": [
    {
      "name": "contractor-A",
      "rules": [{
        "period": { "from": "2024-01-01T00:00:00Z", "to": "2024-01-07T23:59:59Z" },
        "jobTypeLimitations": { "Install": 10 },
        "groupTag": "contractor-install-pool"
      }],
      "shifts": [ /* ... */ ]
    },
    {
      "name": "contractor-B",
      "rules": [{
        "period": { "from": "2024-01-01T00:00:00Z", "to": "2024-01-07T23:59:59Z" },
        "jobTypeLimitations": { "Install": 10 },
        "groupTag": "contractor-install-pool"
      }],
      "shifts": [ /* ... */ ]
    }
  ]
}

Both contractors share a single 10-job pool. Acceptable assignments include 10/0, 5/5, 7/3 — anything whose sum stays at or below 10. Rules for pool membership:

groupTag is a free identifier you choose; it is not related to Resource.tags.
Every resource that should share the pool declares an identical rule (same period and same field values) with the same groupTag.
The first declaration encountered is canonical. Any later declaration that doesn’t match the canonical period or fields is excluded from the pool and a warning is logged — that resource simply doesn’t participate. The remaining matching resources still form the pool.
A pool with one declaring resource behaves like a per-resource rule.
A resource may belong to multiple pools by declaring multiple rules with different groupTag values.
All rule fields (min/maxWorkTime, min/maxServiceTime, min/maxDriveTime, min/maxJobComplexity, jobTypeLimitations) apply collectively when pooled.

Best Practices

Start Conservative

Set limits slightly below legal requirements for buffer

Precompute Windows

Since period is explicit, generate the from/to values for each day/week/month window client-side before building the request.

Combine Daily and Weekly Rules

Declare both granularities on the same resource for comprehensive control

Monitor Utilization

Compare a resource’s totalServiceTimeInSeconds and related response fields against your rule values to see how close it is to its limits

Troubleshooting

Rules seem to have no effect

Possible cause: The field is misspelled or misplaced — a stray/renamed field (e.g. periodRules instead of rules, or a type/value wrapper around the limit) is silently dropped during parsing rather than rejected, so the resource ends up with no constraints at all.Check: Confirm the resource has a top-level rules array (not periodRules), and that each entry uses direct fields like maxWorkTime/maxDriveTime rather than a type/value pair.

Jobs Not Assigned Due to Period Rules

Symptoms: Jobs remain unassigned even though resources appear to have free capacity.Check:

The exact from/to bounds on each rule — a window that doesn’t cover the shift you expect won’t constrain it, and one that’s too broad may combine more work than intended.
Whether the limit is a max* (hard) or min* (medium) field — only max* violations will block an assignment outright.

Solutions:

Add more resources or shifts
Loosen the rule value or widen the window
Distribute work across more days

Performance Impact

Symptoms: Slow solving with many rules.Check:

Number of rules per resource
How many distinct pools (groupTag values) are in play

Solutions:

Limit rules to the ones you actually need enforced
Avoid unnecessarily narrow windows that force many separate rule entries

Resource Management

Basic resource configuration

Break Management

Daily break requirements

Advanced Constraints

Other resource constraints

Time Scheduling

Multi-day shift patterns

Platform

VRP API

Fill API

Resource Period Rules

Resource Period Rules

Period Rule Configuration

Rule Fields

Work Time Rules

Drive Time Rules

Service Time Rules

Building Daily, Weekly, and Monthly Windows

Legal Compliance Examples

EU Drivers’ Hours

US DOT Hours of Service

Enforcement Tiers

Complex Scenarios

Quota Management

Job-Type Quotas

Pooled Rules (`groupTag`)

Best Practices

Troubleshooting

Resource Management

Break Management

Advanced Constraints

Time Scheduling

​Resource Period Rules

​Period Rule Configuration

​Rule Fields

​Work Time Rules

​Drive Time Rules

​Service Time Rules

​Building Daily, Weekly, and Monthly Windows

​Legal Compliance Examples

​EU Drivers’ Hours

​US DOT Hours of Service

​Enforcement Tiers

​Complex Scenarios

​Quota Management

​Job-Type Quotas

​Pooled Rules (groupTag)

​Best Practices

​Troubleshooting

​Related Features

Resource Management

Break Management

Advanced Constraints

Time Scheduling

Resource Period Rules

Period Rule Configuration

Rule Fields

Work Time Rules

Drive Time Rules

Service Time Rules

Building Daily, Weekly, and Monthly Windows

Legal Compliance Examples

EU Drivers’ Hours

US DOT Hours of Service

Enforcement Tiers

Complex Scenarios

Quota Management

Job-Type Quotas

Pooled Rules (`groupTag`)

Best Practices

Troubleshooting

Related Features