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

Hard Tags

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.

{
  "tags": [
    {"name": "forklift-license", "hard": true}
  ]
}

Soft Tags

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": {
      "tagWeight": 1.0  // Global multiplier
    }
  }
}

Tag Weight Calculation

Penalty Formula: penalty = tagWeight × tagWeightGlobal × numberOfMismatchesExample: 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": [
        {"name": "Technician A", "ranking": 1},   // Most preferred
        {"name": "Technician B", "ranking": 10},  // Second choice
        {"name": "Technician C", "ranking": 50},  // Acceptable
        {"name": "Technician D", "ranking": 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

31-70: Neutral

Acceptable assignments

71-100: Discouraged

Use only if necessary

Combining Tags and Rankings

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": [
        {"name": "Expert Installer 1", "ranking": 5},
        {"name": "Expert Installer 2", "ranking": 8},
        {"name": "Standard Installer 1", "ranking": 25},
        {"name": "Standard Installer 2", "ranking": 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": [
        {"name": "John Tech", "ranking": 1},  // Always requests John
        {"name": "Mary Tech", "ranking": 15}, // Acceptable alternative
        {"name": "New Tech", "ranking": 90}   // Avoid sending new staff
      ]
    }
  ]
}

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": {
      "tagWeight": 10,   // Moderate tag importance
      "rankingWeight": 5,         // Moderate ranking importance
      "travelTimeWeight": 1,      // Still optimize routes
      "urgencyWeight": 20         // Priority jobs first
    }
  }
}

Skill-Critical Operations

{
  "options": {
    "weights": {
      "tagWeight": 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

Wrong Resources Assigned

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

Common Causes:

Too many unique tags
Complex soft tag combinations
Many rankings per job

Solutions:

Consolidate similar tags
Use hard tags when possible
Limit rankings to key resources

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": [
        {"name": "Afternoon Specialist", "ranking": 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

Resource Management

Configure resource capabilities

Advanced Constraints

Additional matching rules

Cost Optimization

Balance skills with costs

Job Relations

Complex job dependencies

Platform

VRP API

Tag & Ranking System

Tag & Ranking System

Tag System Overview

Tag Matching Rules

Hard Tags

Soft Tags

Tag Weight Calculation

Ranking System

Ranking Scale

Combining Tags and Rankings

Real-World Examples

Customer Preferences

Skill-Based Assignment

Equipment-Based Matching

Advanced Patterns

Hierarchical Skills

Team Assignments

Best Practices

Configuration Strategies

Balanced Approach

Skill-Critical Operations

Troubleshooting

Integration Examples

With Time Windows

With Regions

Resource Management

Advanced Constraints

Cost Optimization

Job Relations

Platform

VRP API

​Tag & Ranking System

​Tag System Overview

​Tag Matching Rules

​Hard Tags

​Soft Tags

​Tag Weight Calculation

​Ranking System

​Ranking Scale

​Combining Tags and Rankings

​Real-World Examples

​Customer Preferences

​Skill-Based Assignment

​Equipment-Based Matching

​Advanced Patterns

​Hierarchical Skills

​Team Assignments

​Best Practices

​Configuration Strategies

​Balanced Approach

​Skill-Critical Operations

​Troubleshooting

​Integration Examples

​With Time Windows

​With Regions

​Related Features

Resource Management

Advanced Constraints

Cost Optimization

Job Relations

Tag & Ranking System

Tag System Overview

Tag Matching Rules

Hard Tags

Soft Tags

Tag Weight Calculation

Ranking System

Ranking Scale

Combining Tags and Rankings

Real-World Examples

Customer Preferences

Skill-Based Assignment

Equipment-Based Matching

Advanced Patterns

Hierarchical Skills

Team Assignments

Best Practices

Configuration Strategies

Balanced Approach

Skill-Critical Operations

Troubleshooting

Integration Examples

With Time Windows

With Regions

Related Features