Job Relations
Job relations allow you to define dependencies and constraints between multiple jobs in your VRP optimization. These relations ensure that certain business rules are respected when the solver creates routes.Overview
Job relations are defined using therelations
array within each job. Each relation specifies:
- A
type
indicating the constraint type - A list of
jobs
that are part of this relation - Additional parameters specific to each relation type
Available Relation Types
SEQUENCE
Jobs must be visited in the specified order, but other jobs can be scheduled between them.The time intervals specify the gap between when one job ends and the next job begins. This is useful for ensuring adequate travel time or preparation between related tasks.
- Multi-stop deliveries where order matters
- Service appointments with dependencies
- Workflows requiring specific sequences
DIRECT_SEQUENCE
Jobs must be visited in the exact order with no other jobs scheduled between them.- Immediate transfer operations
- Time-critical handoffs
- Continuous processes that cannot be interrupted
SAME_TRIP
All jobs in the relation must be assigned to the same route/trip.- Consolidation requirements
- Grouped deliveries
- Ensuring related tasks stay together
SAME_TIME
Jobs must start or end within a specified time window of each other, with optional minimum time intervals. Optionally enforces resource compatibility constraints to ensure only authorized resources work together.When
enforceCompatibility
is true, the solver ensures that only compatible resources work together on SAME_TIME related jobs. Resources must define their compatible partners using the compatibleResources
field.Minimum Time Interval Behavior:
When minTimeInterval
is specified, the last job in the jobs
array must arrive/depart at least minTimeInterval
seconds after all other jobs. This is useful for staggered arrivals or ensuring adequate spacing between operations.- Synchronized operations
- Team installations
- Coordinated services
- Healthcare teams requiring authorized personnel
- Security operations with supervision requirements
- Training scenarios with approved mentors
- Staggered arrivals at loading docks
- Sequential processing with minimum gaps
SAME_RESOURCE
All jobs must be assigned to the same resource/vehicle (can be on different days).- Customer preference for specific technician
- Specialized equipment requirements
- Continuity of service
PICKUP_AND_DELIVERY
Enforces that pickup happens before delivery, with both assigned to the same resource.- Courier services
- Equipment rental returns
- Any pickup/delivery pair
NEIGHBOR
Jobs should be scheduled consecutively by the same resource (flexible order).- Minimizing travel between related stops
- Clustered service areas
- Efficiency optimization
SAME_DAY
All jobs must be completed on the same calendar day.- Same-day delivery services
- Daily batch processing
- Time-sensitive operations
GROUP_SEQUENCE
Enforces ordering between groups of jobs based on tags.- Priority-based scheduling
- Phased operations
- Category-based ordering
FIRST_JOB
Ensures a job is scheduled as the first stop for a resource.- Morning warehouse pickups
- Mandatory first stops
- Initial setup requirements
Complete Example
Here’s a comprehensive example showing multiple relation types working together:Resource Compatibility
Resource compatibility allows you to control which resources can work together on SAME_TIME related jobs. This is essential for scenarios requiring specific team compositions, authorization levels, or supervision requirements.Configuring Resource Compatibility
Add thecompatibleResources
field to your resource definitions:
Compatibility Rules
- Mutual Compatibility: For two resources to work together, both must list each other
- One-Way Compatibility: Useful for supervision scenarios where only one resource needs authorization
- Open Compatibility: Resources without
compatibleResources
can work with anyone
Example: Healthcare Team
Example: Security Team with Supervision
Important Considerations:
- Compatibility violations result in hard constraints (infeasible solutions)
- Only applies when
enforceCompatibility: true
on SAME_TIME relations - Overly restrictive compatibility can lead to no feasible solutions
- Always validate your compatibility configuration with test requests
Best Practices
When using job relations, consider these best practices:
- Start Simple: Begin with basic relations and add complexity as needed
- Avoid Over-constraining: Too many relations can make the problem infeasible
- Use Partial Planning: Enable
partialPlanning
for relations that might be too restrictive - Test Incrementally: Add relations one at a time to identify conflicts
- Monitor Performance: Complex relations can increase solve time
- Resource Compatibility: When using
enforceCompatibility
, ensure resources have properly configuredcompatibleResources
lists - Validate Compatibility: Test your compatibility configuration with sample requests before production use
Troubleshooting
Common issues when using job relations:
- Infeasible Solutions: Too many conflicting relations
- Long Solve Times: Complex relation networks require more computation
- Unexpected Results: Relations might interact in non-obvious ways
Use the
/v2/vrp/jobs/{id}/explanation
endpoint to understand why certain relations couldn’t be satisfied in your solution.Related Features
- Time Windows - Combine with relations for complex scheduling
- Multi-Day Planning - Use SAME_DAY and SAME_RESOURCE across days
- Capacities - Relations respect capacity constraints
- Resources - Configure resource compatibility for team-based operations