Assignment Automation

​

Understanding Assignment Rules

• Automatically assign tickets to agents or teams based on conditions
• Balance workload across team members
• Route by expertise to ensure proper skill matching
• Operate in priority order when multiple rules match
• Support scheduling for time-based assignments

​

Assignment Rule Components

​

Basic Settings

• Rule Name: Descriptive identifier
• Description: Purpose and scope of the rule
• Priority: Order of evaluation (higher priority = evaluated first)
• Disabled: Toggle to deactivate without deleting

​

Assignment Conditions

• Assign Condition: When to assign tickets (JSON or Python expression)
• Unassign Condition: When to remove assignments
• Document Type: Always “HD Ticket” for Frappe Helpdesk

​

Assignees

• Users: List of agents who can receive assignments
• Assignment Strategy: How to distribute tickets among users

​

Creating Assignment Rules

[["ticket_type", "==", "Bug"], ["priority", "==", "High"]]

doc.ticket_type == 'Bug' and doc.priority == 'High'

[["status", "==", "Closed"]]

​

Assignment Conditions

​

Condition Format

// Single condition
[["status", "==", "Open"]]

// Multiple conditions (AND)
[
  ["ticket_type", "==", "Bug"],
  ["priority", "in", ["High", "Urgent"]]
]

// Complex conditions
[
  ["agent_group", "==", "Support Team"],
  ["customer", "!=", null]
]

# Simple condition
doc.status == 'Open'

# Complex logic
doc.ticket_type == 'Bug' and doc.priority == 'High' and doc.customer == 'Enterprise Corp'

# Using helper functions
is_business_hours() and doc.priority == 'Urgent'

​

Available Fields

• subject, description
• status, priority, ticket_type
• agent_group, raised_by, customer
• via_customer_portal, is_first_ticket
• sla, template
• Custom fields you’ve added

​

Condition Validation

• JSON format must be valid
• Python expressions must be syntactically correct
• Use the portal view to avoid syntax errors

​

Assignment Strategies

​

Round Robin

1. First ticket → First user
2. Second ticket → Second user
3. Last ticket → Last user
4. Next ticket → Back to first user

​

Load Balancing

• Counts open tickets assigned to each user
• Assigns to user with lowest count
• Helps prevent agent overload

​

Based on Field

• Match agent based on ticket property
• Useful for territory, product, or customer-based routing
• Requires field to contain agent ID or email

​

Agent Groups and Teams

​

Team-Based Assignment

[["agent_group", "==", "QA Team"]]

​

Restricting by Agent Group

• Restrict Tickets by Agent Group: Agents only see tickets for their groups
• Assign Within Team: Ensure tickets stay within assigned team
• Do Not Restrict Tickets Without Group: Allow flexible handling of ungrouped tickets

​

Assignment Scheduling

​

Time-Based Rules

from frappe.utils import now_datetime
hour = now_datetime().hour
8 <= hour < 16  # Morning shift

​

Weekend and Holiday Routing

# Weekend condition
from frappe.utils import now_datetime
now_datetime().weekday() in [5, 6]  # Saturday, Sunday

# Holiday condition
from frappe.utils import is_holiday
is_holiday(doc.sla.holiday_list)

​

Priority and Rule Order

​

Priority Best Practices

1. Highest Priority (9-10): Urgent or VIP customer rules
2. High Priority (7-8): Time-sensitive or critical tickets
3. Medium Priority (4-6): Specific routing by type or category
4. Low Priority (1-3): General catch-all rules
5. Base Priority (0): Default fallback rule

​

Base Support Rotation

• Named “Base Support Rotation”
• Priority: 0
• Serves as catch-all for unmatched tickets
• Referenced in HD Settings (hd_settings.json:90-95)

​

Manual Assignment Override

​

Manual Assignment

​

Self-Assignment

# Implementation in helpdesk/api/ticket.py:5-19
def assign_ticket_to_agent(ticket_id, agent_id=None):
    if not agent_id:
        # assign to self
        agent_id = frappe.session.user
    
    # Validation: only agents can be assigned
    if not frappe.db.exists("HD Agent", agent_id):
        frappe.throw(_("Tickets can only be assigned to agents"))

​

Workload Distribution

​

Preventing Overload

1. Count Open Tickets: System counts tickets per agent
2. Assign to Least Loaded: New ticket goes to agent with fewest open tickets
3. Rebalance on Status Change: Counts update when tickets are resolved

​

Capacity Limits

# Custom condition to check agent capacity
agent_ticket_count = frappe.db.count('HD Ticket', {
    '_assign': ['like', f'%{agent.name}%'],
    'status_category': 'Open'
})
agent_ticket_count < 20  # Max 20 open tickets per agent

​

Unassignment Automation

​

Unassign on Resolution

[["status_category", "==", "Resolved"]]

​

Unassign on Transfer

[["agent_group", "!=", "Support Team"]]

​

Unassign on Escalation

doc.priority == 'Urgent' and doc.status == 'Escalated'

​

Notifications

1. Agent Notification: Assigned agent receives an in-app notification
2. Notification Type: “Assignment” notification (see hd_ticket.py:232-241)
3. Email Notification: Optional email alert based on agent preferences

​

Testing Assignment Rules

​

Common Assignment Patterns

​

By Ticket Type

// Billing tickets to billing team
[["ticket_type", "==", "Billing"]]

// Technical tickets to technical team
[["ticket_type", "==", "Technical Issue"]]

​

By Customer Tier

# Enterprise customers to senior agents
customer_tier = frappe.db.get_value('Customer', doc.customer, 'tier')
customer_tier == 'Enterprise'

​

By Priority

// Urgent tickets to senior team
[["priority", "in", ["Urgent", "High"]]]

​

By Channel

# Phone tickets to phone support team
doc.content_type == 'Phone'

# Email tickets to email team
not doc.via_customer_portal

​

By First-Time Customer

// New customers to onboarding team
[["is_first_ticket", "==", 1]]

​

By Agent Group

// Route within assigned team
[["agent_group", "==", "Support Team"]]

​

Best Practices

​

Rule Design

1. Start Simple: Begin with basic rules and add complexity as needed
2. Use Clear Names: Descriptive names help with troubleshooting
3. Document Conditions: Add descriptions explaining rule logic
4. Test Thoroughly: Verify rules work as expected before going live
5. Monitor Performance: Track metrics to ensure rules are effective

​

Condition Writing

1. Use Portal Builder: Visual builder prevents syntax errors
2. Keep Conditions Simple: Complex logic is harder to maintain
3. Avoid Hardcoding: Use dynamic lookups instead of static values
4. Handle Null Values: Check for existence before comparing
5. Test Edge Cases: Verify behavior with missing or unusual data

​

Team Management

1. Balance Workload: Use load balancing for fair distribution
2. Match Expertise: Route tickets to qualified agents
3. Cross-Train Teams: Avoid single points of failure
4. Set Capacity Limits: Prevent agent overload
5. Review Regularly: Adjust rules as team composition changes

​

Maintenance

1. Audit Rules Quarterly: Review and update outdated rules
2. Remove Unused Rules: Delete or disable rules no longer needed
3. Update Assignee Lists: Keep agent lists current
4. Monitor Assignment Metrics: Track which rules are most active
5. Gather Team Feedback: Ask agents if routing is effective

​

Troubleshooting

​

Tickets Not Assigned

1. Check that assignment rules are enabled
2. Verify conditions match ticket properties
3. Ensure assignee list includes active agents
4. Review rule priority order
5. Check for validation errors in conditions

​

Wrong Agent Assigned

1. Review rule conditions for accuracy
2. Check priority order of rules
3. Verify ticket field values match expected
4. Test conditions with sample data
5. Review agent group membership

​

Uneven Distribution

1. Use load balancing instead of round-robin
2. Check if agent is in multiple assignment rules
3. Review manual assignment overrides
4. Verify all agents are active
5. Consider implementing capacity limits

​

Rules Not Evaluating

1. Check that document type is “HD Ticket”
2. Verify rule is not disabled
3. Check for syntax errors in conditions
4. Review system logs for errors
5. Ensure base support rotation exists

​

Related Resources

• Ticket Management
• SLA Configuration