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": [
    {
      "name": "Technician 1",
      "tags": [
        {"name": "electrical-certified", "hard": true},
        {"name": "high-voltage", "hard": true},
        {"name": "senior", "hard": false}
      ],
      "shifts": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    }
  ],
  "jobs": [
    {
      "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}
  ]
}

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

{
  "tags": [
    {"name": "standard-driver", "hard": true}
    // Missing forklift-license
  ]
}

Soft Tags

Preferences that create penalties when not matched:

{
  "resources": [
    {
      "name": "Technician 1",
      "shifts": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    }
  ],
  "jobs": [
    {
      "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
      ]
    }
  ]
}

Tag Weight Calculation

There is no global tag-weight multiplier. Each soft tag carries its own weight, which is applied directly as the penalty when the tag isn’t matched — measured in the same units as travel time (a weight of 3600 is equivalent to one hour of extra travel time).Example: A soft tag {"name": "senior", "weight": 100} that goes unmatched contributes a penalty of 100, on the same scale as travelTimeWeight.

Ranking System

Rankings provide fine-grained resource preferences on a 1-100 scale:

{
  "resources": [
    {
      "name": "Technician A",
      "shifts": [{"from": "2024-03-15T08:00:00Z", "to": "2024-03-15T17:00:00Z"}]
    },
    {
      "name": "Technician B",
      "shifts": [{"from": "2024-03-15T08:00:00Z", "to": "2024-03-15T17:00:00Z"}]
    }
  ],
  "jobs": [
    {
      "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
      ]
    }
  ],
  "weights": {
    "rankingWeight": 2  // 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": [
    {
      "name": "Expert Installer 1",
      "shifts": [{"from": "2024-03-15T08:00:00Z", "to": "2024-03-15T17:00:00Z"}]
    }
  ],
  "jobs": [
    {
      "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:

Setup
Result

{
  "resources": [
    {
      "name": "John Tech",
      "shifts": [{"from": "2024-03-15T08:00:00Z", "to": "2024-03-15T17:00:00Z"}]
    },
    {
      "name": "Mary Tech",
      "shifts": [{"from": "2024-03-15T08:00:00Z", "to": "2024-03-15T17:00:00Z"}]
    },
    {
      "name": "New Tech",
      "shifts": [{"from": "2024-03-15T08:00:00Z", "to": "2024-03-15T17:00:00Z"}]
    }
  ],
  "jobs": [
    {
      "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": [
    {
      "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": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
      // Perfect match - will be strongly preferred
    }
  ],
  "jobs": [
    {
      "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": [
    {
      "name": "Truck 1",
      "category": "TRUCK",
      "tags": [
        {"name": "truck-5ton", "hard": true},
        {"name": "lift-gate", "hard": true},
        {"name": "refrigerated", "hard": true},
        {"name": "gps-tracked", "hard": true}
      ],
      "shifts": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    }
  ],
  "jobs": [
    {
      "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": [
    {
      "name": "Master Electrician",
      "tags": [
        {"name": "electrical-basic", "hard": true},
        {"name": "electrical-advanced", "hard": true},
        {"name": "electrical-master", "hard": true},
        {"name": "trainer", "hard": true}
      ],
      "shifts": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    },
    {
      "name": "Junior Electrician",
      "tags": [
        {"name": "electrical-basic", "hard": true}
      ],
      "shifts": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    }
  ],
  "jobs": [
    {
      "name": "Example Job"
    }
  ]
}

Team Assignments

Use tags to keep teams together:

{
  "resources": [
    {
      "name": "Lead Installer",
      "tags": [{"name": "team-alpha", "hard": true}],
      "shifts": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    },
    {
      "name": "Assistant Installer",
      "tags": [{"name": "team-alpha", "hard": true}],
      "shifts": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z"
        }
      ]
    }
  ],
  "jobs": [
    {
      "name": "Team Installation 1",
      "tags": [{"name": "team-alpha", "hard": true}]
    },
    {
      "name": "Team Installation 2",
      "tags": [{"name": "team-alpha", "hard": true}]
    }
  ]
}

Best Practices

Configuration Strategies

Balanced Approach

There is no global tag-importance weight — tune each soft tag’s own weight value on the job/resource, and balance it against the other objective weights below:

{
  "weights": {
    "rankingWeight": 5,         // Moderate ranking importance
    "travelTimeWeight": 1,      // Still optimize routes
    "urgencyWeight": 20         // Priority jobs first
  }
}

Skill-Critical Operations

Raise the weight on individual soft tags (e.g. {"name": "cisco-certified", "hard": false, "weight": 5000}) so skill mismatches dominate, and pair that with:

{
  "weights": {
    "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": [
    {
      "name": "Afternoon Specialist",
      "shifts": [{"from": "2024-03-15T14:00:00Z", "to": "2024-03-15T17:00:00Z"}]
    }
  ],
  "jobs": [
    {
      "name": "Afternoon Service",
      "windows": [{"from": "2024-03-15T14:00:00Z", "to": "2024-03-15T17:00:00Z"}],
      "rankings": [
        {"name": "Afternoon Specialist", "ranking": 1}
      ]
    }
  ]
}
// Only assigns if resource available in window

With Regions

Resource.region is a single geographic point (not a named zone or list), expressing a soft preference for keeping that resource working near it. There’s no equivalent region field on a job — combine a resource’s region with tags for skill matching and rely on the job’s own location for the geographic side:

{
  "resources": [
    {
      "name": "Technician 1",
      "region": {"latitude": 51.09, "longitude": 3.73},
      "tags": [{"name": "electrical-certified", "hard": true}],
      "shifts": [{"from": "2024-03-15T08:00:00Z", "to": "2024-03-15T17:00:00Z"}]
    }
  ],
  "jobs": [
    {
      "name": "North Electrical Job",
      "location": {"latitude": 51.095, "longitude": 3.735},
      "tags": [
        {"name": "electrical-certified", "hard": true}
      ]
    }
  ]
}
// The tag makes certification a hard requirement; the resource's `region` is a soft
// preference (tuned via `regionMinimisationWeight`) for staying near that point

Resource Management

Configure resource capabilities

Advanced Constraints

Additional matching rules

Cost Optimization

Balance skills with costs

Job Relations

Complex job dependencies

Platform

VRP API

Fill 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

​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