Job Complexity

Job complexity allows you to assign difficulty scores to jobs and ensure fair workload distribution across resources. This feature helps balance not just the number of jobs or time spent, but the actual difficulty and mental/physical load on workers.

Overview

The complexity feature enables:

Assigning complexity scores to jobs based on difficulty
Fair distribution of complex work across resources
Setting min/max complexity limits per resource period
Balancing complexity per trip or per resource

Basic Complexity Configuration

Setting Job Complexity

Assign complexity values to jobs on a scale that makes sense for your business:

{
  "jobs": [
    {
      "name": "simple-delivery",
      "location": {"latitude": 52.520, "longitude": 13.405},
      "duration": 1800,
      "complexity": 1  // Simple task
    },
    {
      "name": "technical-installation",
      "location": {"latitude": 52.523, "longitude": 13.401},
      "duration": 3600,
      "complexity": 5  // Complex task requiring expertise
    },
    {
      "name": "hazardous-material-handling",
      "location": {"latitude": 52.517, "longitude": 13.388},
      "duration": 2700,
      "complexity": 8  // High complexity due to safety requirements
    }
  ],
  "resources": [
    {
      "name": "senior-tech",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }]
    },
    {
      "name": "junior-tech",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }]
    }
  ]
}

Choose a complexity scale that reflects your business needs. Common scales include:

1-10 (simple to very complex)
1-100 (fine-grained difficulty)
1-5 (basic categorization)

Fair Complexity Distribution

Balancing Complexity Per Trip

Ensure each trip has a balanced mix of complex and simple jobs:

{
  "options": {
    "fairComplexityPerTrip": true
  },
  "jobs": [
    {
      "name": "complex-repair",
      "complexity": 8,
      "duration": 3600
    },
    {
      "name": "routine-check-1",
      "complexity": 2,
      "duration": 1200
    },
    {
      "name": "routine-check-2",
      "complexity": 2,
      "duration": 1200
    },
    {
      "name": "moderate-task",
      "complexity": 5,
      "duration": 2400
    }
  ]
}

Balancing Complexity Per Resource

Distribute total complexity fairly across all resources:

{
  "options": {
    "fairComplexityPerResource": true
  }
}

fairComplexityPerResource is a boolean toggle only — there is no fairComplexityPerResourceWeight (or any other weight) that scales how strongly it’s enforced. Turning it on tells the solver to try to ensure each resource gets a similar total complexity score across their shifts, preventing burnout from consistently handling difficult tasks.

Resource Period Complexity Limits

Set minimum and maximum complexity constraints per period using the resource’s rules array (not periods). There is no rolling WEEK/DAY keyword — period is always an explicit { "from", "to" } date-time window that you compute yourself, and each rule entry has no name property:

{
  "resources": [
    {
      "name": "experienced-tech",
      "rules": [
        {
          "period": { "from": "2024-03-11T00:00:00Z", "to": "2024-03-18T00:00:00Z" },
          "maxJobComplexity": 100,  // Max 100 complexity points that week
          "minJobComplexity": 20    // At least 20 points (avoid underutilization)
        }
      ],
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }]
    },
    {
      "name": "new-tech",
      "rules": [
        {
          "period": { "from": "2024-03-15T00:00:00Z", "to": "2024-03-16T00:00:00Z" },
          "maxJobComplexity": 15  // Limited complexity during training, that day
        }
      ],
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }]
    }
  ]
}

See Resource Period Rules for the full rules/period schema, including how to build daily/weekly/monthly windows and pool rules across resources with groupTag.

Use Cases

Skill-Based Workload Management

Balance complex technical work across skilled technicians:

{
  "jobs": [
    {
      "name": "server-migration",
      "complexity": 10,  // Highest complexity
      "tags": [{"name": "senior-only", "hard": true}]
    },
    {
      "name": "cable-installation",
      "complexity": 3,
      "tags": [{"name": "certified-tech", "hard": true}]
    },
    {
      "name": "routine-maintenance",
      "complexity": 1
    }
  ],
  "options": {
    "fairComplexityPerResource": true
  }
}

Physical Demand Balancing

Distribute physically demanding tasks fairly:

{
  "jobs": [
    {
      "name": "heavy-lifting-delivery",
      "complexity": 8,  // High physical demand
      "load": [200]     // 200kg
    },
    {
      "name": "document-delivery",
      "complexity": 1,  // Low physical demand
      "load": [5]       // 5kg
    }
  ],
  "resources": [
    {
      "name": "driver-1",
      "rules": [{
        "period": { "from": "2024-03-15T00:00:00Z", "to": "2024-03-16T00:00:00Z" },
        "maxJobComplexity": 40  // Limit daily physical strain
      }]
    }
  ]
}

Mental Load Distribution

Balance cognitively demanding tasks:

{
  "jobs": [
    {
      "name": "security-audit",
      "complexity": 9,  // High mental load
      "duration": 14400 // 4 hours
    },
    {
      "name": "routine-inspection",
      "complexity": 2,  // Low mental load
      "duration": 3600  // 1 hour
    }
  ],
  "options": {
    "fairComplexityPerTrip": true  // Mix complex and simple in each trip
  }
}

Integration with Other Features

With Tags and Skills

Combine complexity with skill requirements:

{
  "jobs": [
    {
      "name": "advanced-repair",
      "complexity": 8,
      "tags": [
        {"name": "certified", "hard": true},
        {"name": "experienced", "weight": 50}
      ]
    }
  ]
}

With Time Windows

Complex jobs during optimal hours:

{
  "jobs": [
    {
      "name": "precision-work",
      "complexity": 10,
      "windows": [
        {"from": "2024-03-15T09:00:00Z", "to": "2024-03-15T12:00:00Z"}  // Morning when fresh
      ]
    }
  ]
}

Best Practices

Define Clear Complexity Scale

Create a documented scale that all planners understand and apply consistently

Consider Multiple Factors

Include physical demand, mental load, risk level, and skill requirements in complexity scores

Monitor Distribution

Use the solution’s complexity distribution to ensure fairness over time

Toggle Deliberately

fairComplexityPerTrip and fairComplexityPerResource are on/off booleans with no dedicated weight — decide which one(s) fit your priorities rather than trying to tune a weight

Constraints and Violations

The following constraints relate to complexity:

Constraint	Description	Type
`RESOURCE_PERIOD_MAX_COMPLEXITY`	Exceeded maximum complexity in period	hard
`RESOURCE_PERIOD_MIN_COMPLEXITY`	Below minimum complexity in period	medium
`FAIR_COMPLEXITY_PER_TRIP`	Uneven complexity distribution in trips	soft
`FAIR_COMPLEXITY_PER_RESOURCE`	Uneven complexity across resources	soft

Tips for Implementation

Start Conservative: Begin with optional complexity (soft constraints) before making them mandatory. This helps identify appropriate limits.

Review Regularly: Analyze complexity distribution in solutions to refine your scoring system and limits.

Combine with Fairness: Use complexity alongside the general work fairness features for comprehensive workload balancing.

Resource Management

Configure resource capabilities and periods

Fair Work Distribution

General work fairness features

Tag & Ranking

Skill-based job assignment

Time Scheduling

Coordinate complex jobs with timing

Platform

VRP API

Fill API

Job Complexity

Job Complexity

Overview

Basic Complexity Configuration

Setting Job Complexity

Fair Complexity Distribution

Balancing Complexity Per Trip

Balancing Complexity Per Resource

Resource Period Complexity Limits

Use Cases

Skill-Based Workload Management

Physical Demand Balancing

Mental Load Distribution

Integration with Other Features

With Tags and Skills

With Time Windows

Best Practices

Constraints and Violations

Tips for Implementation

Resource Management

Fair Work Distribution

Tag & Ranking

Time Scheduling

​Job Complexity

​Overview

​Basic Complexity Configuration

​Setting Job Complexity

​Fair Complexity Distribution

​Balancing Complexity Per Trip

​Balancing Complexity Per Resource

​Resource Period Complexity Limits

​Use Cases

​Skill-Based Workload Management

​Physical Demand Balancing

​Mental Load Distribution

​Integration with Other Features

​With Tags and Skills

​With Time Windows

​Best Practices

​Constraints and Violations

​Tips for Implementation

​Related Features

Resource Management

Fair Work Distribution

Tag & Ranking

Time Scheduling

Job Complexity

Overview

Basic Complexity Configuration

Setting Job Complexity

Fair Complexity Distribution

Balancing Complexity Per Trip

Balancing Complexity Per Resource

Resource Period Complexity Limits

Use Cases

Skill-Based Workload Management

Physical Demand Balancing

Mental Load Distribution

Integration with Other Features

With Tags and Skills

With Time Windows

Best Practices

Constraints and Violations

Tips for Implementation

Related Features