Skip to main content
Assignment rules automate ticket distribution to agents based on conditions you define. This ensures tickets are routed to the right agents at the right time.

​
Assignment Rules

Assignment rules are created using the Assignment Rule doctype and are specifically configured for HD Ticket.

​
Basic Configuration

​
name
string
required
Unique name for the assignment rule (e.g., “Support Rotation”, “Priority Escalation”).Maximum length: 50 characters.
​
description
text
required
Description of what this rule does and when it applies.Maximum length: 140 characters.
​
priority
number
default:"0"
Rule priority determines execution order. Higher priority rules are evaluated first.Available options:
  • 0: Low
  • 1: Low-Medium
  • 2: Medium
  • 3: Medium-High
  • 4: High
​
disabled
boolean
default:"false"
When enabled, the rule is active and will be evaluated for new/updated tickets.Disabled rules are skipped during assignment processing.

​
Assignment Conditions

Define when tickets should be assigned using this rule.
​
assign_condition_json
JSON
JSON array of conditions that must be met for assignment.Format: [["field", "operator", "value"], ...]Example:
[
  ["status", "==", "Open"],
  ["priority", "in", ["High", "Urgent"]]
]
​
assign_condition
text
Python expression for assignment conditions (legacy format).Example: status == "Open" and priority in ["High", "Urgent"]Note: New rules should use assign_condition_json for better UI compatibility.
Learn more about condition syntax.

​
Unassignment Conditions

Define when tickets should be unassigned.
​
unassign_condition_json
JSON
JSON array of conditions that trigger unassignment.Format: [["field", "operator", "value"], ...]Example:
[
  ["status", "==", "Closed"]
]
​
unassign_condition
text
Python expression for unassignment conditions (legacy format).Example: status == "Closed"

​
Assignment Schedule

Control when the rule is active during the week.
​
assignment_days
Table
Days of the week when this rule should be active.Each entry is an Assignment Rule Day with a day field:
  • Monday
  • Tuesday
  • Wednesday
  • Thursday
  • Friday
  • Saturday
  • Sunday
If empty, the rule is active every day.

​
Assignment Strategy

​
rule
string
default:"Round Robin"
How tickets are distributed among eligible agents.Options:
  • Round Robin: Distribute evenly in rotation
  • Load Balancing: Assign to agent with fewest open tickets
  • Based on Field: Assign based on a ticket field value
​
users
Table
List of users who can receive assignments from this rule.Each entry contains:
  • user: Link to User doctype
Only active agents should be included.

​
Creating Assignment Rules

​
Via API

import frappe

# Create a simple assignment rule
rule = frappe.get_doc({
    "doctype": "Assignment Rule",
    "name": "Support Rotation",
    "description": "Assign open tickets to support team",
    "document_type": "HD Ticket",
    "priority": 2,
    "disabled": False,
    "rule": "Round Robin",
    "assign_condition_json": '[["status", "==", "Open"]]',
    "assign_condition": 'status == "Open"',
    "assignment_days": [
        {"day": "Monday"},
        {"day": "Tuesday"},
        {"day": "Wednesday"},
        {"day": "Thursday"},
        {"day": "Friday"}
    ],
    "users": [
        {"user": "[email protected]"},
        {"user": "[email protected]"},
        {"user": "[email protected]"}
    ]
})
rule.insert()

​
Via UI

The Assignment Rules interface provides a visual builder for conditions:
  1. Navigate to Settings > Assignment Rules
  2. Click “New Assignment Rule”
  3. Enter name and description
  4. Set priority and schedule
  5. Build assignment conditions using the condition builder
  6. Add agents to the assignment pool
  7. Save and enable the rule

​
Base Support Rotation

Frappe Helpdesk automatically creates a base support rotation rule:
​
base_support_rotation
string
The default assignment rule created during setup.Stored in HD Settings and initialized with:
  • Document Type: HD Ticket
  • Condition: status == "Open"
  • All days enabled
  • Disabled by default (enable after adding agents)
Access it programmatically: 
import frappe

settings = frappe.get_single("HD Settings")
base_rule = settings.get_base_support_rotation()
print(f"Base rule: {base_rule}")

​
Condition Examples

​
Priority-Based Assignment

[
  ["priority", "in", ["High", "Urgent"]]
]

​
Status and Type

[
  ["status", "==", "Open"],
  ["ticket_type", "==", "Technical"]
]

​
Time-Based (requires custom fields)

[
  ["status", "==", "Open"],
  ["created_on", ">=", "2024-01-01"]
]

​
Team-Based

[
  ["agent_group", "==", "Technical Support"]
]

​
Rule Evaluation

Assignment rules are evaluated:
  1. On ticket creation: When assign_condition is met
  2. On ticket update: When conditions change
  3. Manual trigger: Via API or workflow actions
Rules are processed in priority order (highest first). The first matching rule assigns the ticket.

​
Updating Assignment Rules

import frappe
from frappe.client import set_value

# Update rule settings
set_value(
    "Assignment Rule",
    "Support Rotation",
    {
        "priority": 3,
        "disabled": False,
        "description": "Updated description"
    }
)

# Add a new user to the pool
rule = frappe.get_doc("Assignment Rule", "Support Rotation")
rule.append("users", {"user": "[email protected]"})
rule.save()

​
Frontend Integration

The assignment rules UI is built with Vue 3 and uses reactive state management: 
import { assignmentRulesActiveScreen } from "@/stores/assignmentRules";

// Navigate to rule view
assignmentRulesActiveScreen.value = {
  screen: "view",
  data: { name: "Support Rotation" }
};

// Navigate to rule list
assignmentRulesActiveScreen.value = {
  screen: "list",
  data: null
};

​
Validation

Assignment rules are validated on save:
  • Name and description are required
  • Name must be unique and ≤50 characters
  • Description must be ≤140 characters
  • Conditions must be valid JSON (when using assign_condition_json)
  • At least one user must be in the assignment pool
  • Users must exist and have Agent role

​
Best Practices

  1. Start Simple: Begin with basic status-based rules before adding complexity
  2. Use JSON Conditions: Prefer assign_condition_json over text conditions for UI compatibility
  3. Test Rules: Create rules as disabled, test thoroughly, then enable
  4. Priority Strategy: Use priorities to handle exceptions (e.g., high priority for urgent tickets)
  5. Schedule Awareness: Use assignment days for business hours coverage
  6. Monitor Load: Use load balancing for teams with varying ticket volumes
  7. Document Rules: Use clear descriptions explaining the rule’s purpose
  8. Regular Review: Audit rules quarterly to ensure they match current workflows

​
Troubleshooting

  • Rule Not Triggering: Check that conditions match ticket fields exactly
  • Wrong Agent: Verify user list and rule priority
  • Schedule Issues: Confirm assignment_days are set correctly
  • Condition Errors: Use JSON format validator before saving
  • No Assignment: Ensure rule is enabled and users are active agents

Build docs developers (and LLMs) love

Get started for freeTalk to us