Tag & Ranking System The tag and ranking system enables sophisticated matching between job requirements and resource capabilities, while also allowing preference-based assignments. This guide covers both hard skill requirements and soft preference rankings.
Tag System Overview Tags represent skills, certifications, equipment, or any other matching criteria:
{ "resources" : [ { "id" : "technician-1" , "name" : "Technician 1" , "tags" : [ { "name" : "electrical-certified" , "hard" : true }, { "name" : "high-voltage" , "hard" : true }, { "name" : "senior" , "hard" : false } ], "shifts" : [ { "id" : "shift1" , "from" : "2024-03-15T08:00:00Z" , "to" : "2024-03-15T17:00:00Z" } ] } ], "jobs" : [ { "id" : "electrical-repair" , "name" : "Electrical Repair" , "tags" : [ { "name" : "electrical-certified" , "hard" : true }, { "name" : "high-voltage" , "hard" : false , "weight" : 50 } ] } ] } Tag Matching Rules Strict requirements that must be matched:
Hard Tag Rule : If a job has a hard tag, only resources with that same hard tag can be assigned to it.
Job Requirement
Valid Resource
Invalid Resource
{ "tags" : [ { "name" : "forklift-license" , "hard" : true } ] }
Preferences that create penalties when not matched:
{ "resources" : [ { "id" : "tech-1" , "name" : "Technician 1" , "shifts" : [ { "id" : "shift1" , "from" : "2024-03-15T08:00:00Z" , "to" : "2024-03-15T17:00:00Z" } ] } ], "jobs" : [ { "id" : "premium-service" , "name" : "Premium Service" , "tags" : [ { "name" : "certified" , "hard" : true }, // Must have { "name" : "senior" , "hard" : false , "weight" : 100 }, // Strongly preferred { "name" : "local-knowledge" , "hard" : false , "weight" : 25 } // Nice to have ] } ], "options" : { "weights" : { "tagViolationWeight" : 1.0 // Global multiplier } } } Tag Weight Calculation Penalty Formula :
penalty = tagWeight × tagViolationWeight × numberOfMismatches
Example: Missing “senior” tag with weight 100 and global weight 1.0 = 100 penalty points
Ranking System Rankings provide fine-grained resource preferences on a 1-100 scale:
{ "resources" : [ { "id" : "technician-a" , "name" : "Technician A" , "shifts" : [{ "id" : "shift1" , "from" : "2024-03-15T08:00:00Z" , "to" : "2024-03-15T17:00:00Z" }] }, { "id" : "technician-b" , "name" : "Technician B" , "shifts" : [{ "id" : "shift1" , "from" : "2024-03-15T08:00:00Z" , "to" : "2024-03-15T17:00:00Z" }] } ], "jobs" : [ { "id" : "vip-customer-service" , "name" : "VIP Customer Service" , "rankings" : [ { "resource" : "technician-a" , "value" : 1 }, // Most preferred { "resource" : "technician-b" , "value" : 10 }, // Second choice { "resource" : "technician-c" , "value" : 50 }, // Acceptable { "resource" : "technician-d" , "value" : 100 } // Last resort ] } ], "options" : { "weights" : { "rankingWeight" : 2.0 // Importance of rankings } } } Ranking Scale
1-10: Strongly Preferred
Primary choices for this job
11-30: Preferred
Good matches with minor preferences
Use both systems together for complex requirements:
{ "resources" : [ { "id" : "expert-installer-1" , "name" : "Expert Installer 1" , "shifts" : [{ "id" : "shift1" , "from" : "2024-03-15T08:00:00Z" , "to" : "2024-03-15T17:00:00Z" }] } ], "jobs" : [ { "id" : "specialized-installation" , "name" : "Specialized Installation" , // Hard requirements "tags" : [ { "name" : "installation-cert" , "hard" : true }, { "name" : "heavy-equipment" , "hard" : true }, { "name" : "customer-favorite" , "hard" : false , "weight" : 50 } ], // Preferences among qualified resources "rankings" : [ { "resource" : "expert-installer-1" , "value" : 5 }, { "resource" : "expert-installer-2" , "value" : 8 }, { "resource" : "standard-installer-1" , "value" : 25 }, { "resource" : "standard-installer-2" , "value" : 30 } ] } ] } Real-World Examples Customer Preferences Track and honor customer preferences:
{ "resources" : [ { "id" : "john-tech" , "name" : "John Tech" , "shifts" : [{ "id" : "shift1" , "from" : "2024-03-15T08:00:00Z" , "to" : "2024-03-15T17:00:00Z" }] }, { "id" : "mary-tech" , "name" : "Mary Tech" , "shifts" : [{ "id" : "shift1" , "from" : "2024-03-15T08:00:00Z" , "to" : "2024-03-15T17:00:00Z" }] }, { "id" : "new-tech" , "name" : "New Tech" , "shifts" : [{ "id" : "shift1" , "from" : "2024-03-15T08:00:00Z" , "to" : "2024-03-15T17:00:00Z" }] } ], "jobs" : [ { "id" : "smith-residence-service" , "name" : "Smith Residence Service" , "rankings" : [ { "resource" : "john-tech" , "value" : 1 }, // Always requests John { "resource" : "mary-tech" , "value" : 15 }, // Acceptable alternative { "resource" : "new-tech" , "value" : 90 } // Avoid sending new staff ] } ] } { "resources" : [ { "id" : "john-tech" , "name" : "John Tech" , "shifts" : [{ "id" : "shift1" , "from" : "2024-03-15T08:00:00Z" , "to" : "2024-03-15T17:00:00Z" }] }, { "id" : "mary-tech" , "name" : "Mary Tech" , "shifts" : [{ "id" : "shift1" , "from" : "2024-03-15T08:00:00Z" , "to" : "2024-03-15T17:00:00Z" }] }, { "id" : "new-tech" , "name" : "New Tech" , "shifts" : [{ "id" : "shift1" , "from" : "2024-03-15T08:00:00Z" , "to" : "2024-03-15T17:00:00Z" }] } ], "jobs" : [ { "id" : "smith-residence-service" , "name" : "Smith Residence Service" , "rankings" : [ { "resource" : "john-tech" , "value" : 1 }, // Always requests John { "resource" : "mary-tech" , "value" : 15 }, // Acceptable alternative { "resource" : "new-tech" , "value" : 90 } // Avoid sending new staff ] } ] } The solver will:
Try to assign john-tech first
Use mary-tech if John unavailable
Only use new-tech if no other option
Skill-Based Assignment Match complex skill requirements:
{ "resources" : [ { "id" : "senior-network-tech" , "name" : "Senior Network Tech" , "tags" : [ { "name" : "network-certified" , "hard" : true }, { "name" : "security-clearance" , "hard" : true }, { "name" : "cisco-certified" , "hard" : true }, { "name" : "10-years-experience" , "hard" : true }, { "name" : "datacenter-specialist" , "hard" : true } ], "shifts" : [ { "id" : "shift1" , "from" : "2024-03-15T08:00:00Z" , "to" : "2024-03-15T17:00:00Z" } ] // Perfect match - will be strongly preferred } ], "jobs" : [ { "id" : "data-center-maintenance" , "name" : "Data Center Maintenance" , "tags" : [ // Required certifications { "name" : "network-certified" , "hard" : true }, { "name" : "security-clearance" , "hard" : true }, // Preferred qualifications { "name" : "cisco-certified" , "hard" : false , "weight" : 75 }, { "name" : "10-years-experience" , "hard" : false , "weight" : 50 }, { "name" : "datacenter-specialist" , "hard" : false , "weight" : 100 } ] } ] } Equipment-Based Matching Ensure proper equipment for each job:
{ "resources" : [ { "id" : "truck-1" , "name" : "Truck 1" , "category" : "VEHICLE" , "tags" : [ { "name" : "truck-5ton" , "hard" : true }, { "name" : "lift-gate" , "hard" : true }, { "name" : "refrigerated" , "hard" : true }, { "name" : "gps-tracked" , "hard" : true } ], "shifts" : [ { "id" : "shift1" , "from" : "2024-03-15T08:00:00Z" , "to" : "2024-03-15T17:00:00Z" } ] } ], "jobs" : [ { "id" : "heavy-delivery" , "name" : "Heavy Delivery" , "tags" : [ { "name" : "truck-5ton" , "hard" : true }, { "name" : "lift-gate" , "hard" : true }, { "name" : "refrigerated" , "hard" : false , "weight" : 30 } ] } ] } Advanced Patterns Hierarchical Skills Model skill levels and specializations:
{ "resources" : [ { "id" : "master-electrician" , "name" : "Master Electrician" , "tags" : [ { "name" : "electrical-basic" , "hard" : true }, { "name" : "electrical-advanced" , "hard" : true }, { "name" : "electrical-master" , "hard" : true }, { "name" : "trainer" , "hard" : true } ], "shifts" : [ { "id" : "shift1" , "from" : "2024-03-15T08:00:00Z" , "to" : "2024-03-15T17:00:00Z" } ] }, { "id" : "junior-electrician" , "name" : "Junior Electrician" , "tags" : [ { "name" : "electrical-basic" , "hard" : true } ], "shifts" : [ { "id" : "shift1" , "from" : "2024-03-15T08:00:00Z" , "to" : "2024-03-15T17:00:00Z" } ] } ], "jobs" : [ { "id" : "job1" , "name" : "Example Job" } ] } Team Assignments Use tags to keep teams together:
{ "resources" : [ { "id" : "lead-installer" , "name" : "Lead Installer" , "tags" : [{ "name" : "team-alpha" , "hard" : true }], "shifts" : [ { "id" : "shift1" , "from" : "2024-03-15T08:00:00Z" , "to" : "2024-03-15T17:00:00Z" } ] }, { "id" : "assistant-installer" , "name" : "Assistant Installer" , "tags" : [{ "name" : "team-alpha" , "hard" : true }], "shifts" : [ { "id" : "shift1" , "from" : "2024-03-15T08:00:00Z" , "to" : "2024-03-15T17:00:00Z" } ] } ], "jobs" : [ { "id" : "team-installation-1" , "name" : "Team Installation 1" , "tags" : [{ "name" : "team-alpha" , "hard" : true }] }, { "id" : "team-installation-2" , "name" : "Team Installation 2" , "tags" : [{ "name" : "team-alpha" , "hard" : true }] } ] } Best Practices Configuration Strategies Balanced Approach { "options" : { "weights" : { "tagViolationWeight" : 10 , // Moderate tag importance "rankingWeight" : 5 , // Moderate ranking importance "travelTimeWeight" : 1 , // Still optimize routes "urgencyWeight" : 20 // Priority jobs first } } } Skill-Critical Operations { "options" : { "weights" : { "tagViolationWeight" : 100 , // Skills very important "rankingWeight" : 20 , // Strong preferences "travelTimeWeight" : 0.5 , // Less important "urgencyWeight" : 10 // Moderate priority } } } Troubleshooting
Jobs Not Assigned Despite Available Resources
Common Causes :
Missing required hard tags
Tag typos (case-sensitive)
Resource doesn’t have all required tags
Debug Steps :
Check exact tag spelling
Verify all hard tags present
Use explanation endpoint
Try removing tags one by one
Common Causes :
Low ranking/tag weights
Competing objectives (travel time)
Missing preference data
Solutions :
Increase rankingWeight
Add explicit rankings
Review all constraint weights
Performance Issues with Many Tags
Integration Examples With Time Windows Rankings respect time availability:
{ "resources" : [ { "id" : "afternoon-specialist" , "name" : "Afternoon Specialist" , "shifts" : [{ "id" : "shift1" , "from" : "2024-03-15T14:00:00Z" , "to" : "2024-03-15T17:00:00Z" }] } ], "jobs" : [ { "id" : "afternoon-service" , "name" : "Afternoon Service" , "windows" : [[ "2024-03-15T14:00:00Z" , "2024-03-15T17:00:00Z" ]], "rankings" : [ { "resource" : "afternoon-specialist" , "value" : 1 } ] } ] } // Only assigns if resource available in window With Regions Combine geographic and skill constraints:
{ "resources" : [ { "id" : "tech-1" , "name" : "Technician 1" , "regions" : [ "north" ], "tags" : [{ "name" : "electrical-certified" , "hard" : true }], "shifts" : [{ "id" : "shift1" , "from" : "2024-03-15T08:00:00Z" , "to" : "2024-03-15T17:00:00Z" }] } ], "jobs" : [ { "id" : "north-electrical" , "name" : "North Electrical Job" , "region" : "north" , "tags" : [ { "name" : "electrical-certified" , "hard" : true } ] } ] } // Needs north region AND certification 
