> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solvice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tag & Ranking System

> Implement skill matching and resource preferences with tags and rankings

# 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:

```json theme={null}
{
  "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:

<Info>
  **Hard Tag Rule**: If a job has a hard tag, only resources with that same hard tag can be assigned to it.
</Info>

<CodeGroup>
  ```json Job Requirement theme={null}
  {
    "tags": [
      {"name": "forklift-license", "hard": true}
    ]
  }
  ```

  ```json Valid Resource theme={null}
  {
    "tags": [
      {"name": "forklift-license", "hard": true}
    ]
  }
  ```

  ```json Invalid Resource theme={null}
  {
    "tags": [
      {"name": "standard-driver", "hard": true}
      // Missing forklift-license
    ]
  }
  ```
</CodeGroup>

### Soft Tags

Preferences that create penalties when not matched:

```json theme={null}
{
  "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

<Note>
  **Penalty Formula**:
  `penalty = tagWeight × tagWeightGlobal × numberOfMismatches`

  Example: Missing "senior" tag with weight 100 and global weight 1.0 = 100 penalty points
</Note>

## Ranking System

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

```json theme={null}
{
  "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

<Steps>
  <Step title="1-10: Strongly Preferred">
    Primary choices for this job
  </Step>

  <Step title="11-30: Preferred">
    Good matches with minor preferences
  </Step>

  <Step title="31-70: Neutral">
    Acceptable assignments
  </Step>

  <Step title="71-100: Discouraged">
    Use only if necessary
  </Step>
</Steps>

## Combining Tags and Rankings

Use both systems together for complex requirements:

```json theme={null}
{
  "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:

<Tabs>
  <Tab title="Setup">
    ```json theme={null}
    {
      "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
          ]
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Result">
    The solver will:

    1. Try to assign john-tech first
    2. Use mary-tech if John unavailable
    3. Only use new-tech if no other option
  </Tab>
</Tabs>

### Skill-Based Assignment

Match complex skill requirements:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<Tips>
  <Tip>
    **Tag Naming Conventions**:

    * Use descriptive, consistent names
    * Include version/level in tag (e.g., "forklift-certified-2024")
    * Group related tags (e.g., "cert-electrical", "cert-plumbing")
  </Tip>

  <Tip>
    **Ranking Guidelines**:

    * Reserve 1-10 for true preferences
    * Use 40-60 for neutral assignments
    * Document ranking rationale
    * Review and update regularly
  </Tip>

  <Tip>
    **Performance Optimization**:

    * Limit unique tags to necessary distinctions
    * Use rankings for preferences over soft tags
    * Keep tag weights proportional
  </Tip>
</Tips>

## Configuration Strategies

### Balanced Approach

```json theme={null}
{
  "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

```json theme={null}
{
  "options": {
    "weights": {
      "tagWeight": 100,  // Skills very important
      "rankingWeight": 20,        // Strong preferences
      "travelTimeWeight": 0.5,    // Less important
      "urgencyWeight": 10         // Moderate priority
    }
  }
}
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="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**:

    1. Check exact tag spelling
    2. Verify all hard tags present
    3. Use explanation endpoint
    4. Try removing tags one by one
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Integration Examples

### With Time Windows

Rankings respect time availability:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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
```

## Related Features

<CardGroup cols={2}>
  <Card title="Resource Management" icon="users" href="/guides/vrp/features/resource-management">
    Configure resource capabilities
  </Card>

  <Card title="Advanced Constraints" icon="shield" href="/guides/vrp/features/advanced-constraints">
    Additional matching rules
  </Card>

  <Card title="Cost Optimization" icon="dollar-sign" href="/guides/vrp/features/cost-optimization">
    Balance skills with costs
  </Card>

  <Card title="Job Relations" icon="link" href="/guides/vrp/features/job-relations">
    Complex job dependencies
  </Card>
</CardGroup>