Task Assignment Recommendations helps dispatchers match technicians to work orders based on the factors that actually determine whether a job gets done right — distance, travel time, parts availability, schedule fit, and mobile capability.

Without it, dispatchers rely on tribal knowledge and manual checks to make assignment calls that should be data-driven. With it, the system surfaces recommended assignments based on configurable criteria, so dispatchers spend less time figuring out who to send and more time handling exceptions.

The recommendation engine is built specifically for field service — not a generic task routing framework — which means the criteria it uses reflect real operational constraints, not abstract matching logic.

## Key Features of Field Service Management Intelligent Task Recommendations

### 1. Core Purpose

This plugin provides intelligent task recommendation functionality for Field Service Management (FSM), enabling the system to recommend optimal work order tasks for assignment to field service technicians based on multiple criteria and constraints.

* * *

### 2. Extension Point Implementation

- Extends the Store Task Recommendations Framework (`sn_task_recommend`)
- Implements `TaskRecommendationEP` extension point via `TaskRecommendationFSMEP`
- Provides FSM-specific implementation of the upstream recommendation engine
- Scope: `sn_fsm_task_rec`
- Depends on: `com.snc.work_management` plugin

* * *

### 3. Intelligent Filtering & Ranking System

#### Distance-Based Recommendations

- `TaskRecommendationDistanceRuleProcessor`: Filters and ranks tasks based on travel distance
- Calculates travel time from agent's current/previous location to task location
- Considers travel time from task back to next location or home
- Integrates with geo-routing services (straight-line or map vendor calculations)
- Validates agent can complete work within available time windows

#### Parts-Based Recommendations

- `TaskRecommendationPartsFilter`: Filters tasks requiring parts the agent doesn't have
- `TaskRecommendationPartsRating`: Ranks tasks based on parts availability match
- Checks agent's personal stockroom inventory
- Validates mandatory vs. optional parts requirements
- Calculates rating based on part model matches and quantities

#### Rejected Technician Filter

- `TaskRecommendationRejectedTechnicianFilter`: Excludes tasks previously rejected by the agent
- Configurable time window (default: 24 hours)
- Supports task bundle integration
- Prevents re-recommending recently declined work

* * *

### 4. Travel Time & Location Management

#### `FSMTravelTimeLocationUtil` - Core utility for location/travel calculations:

- Agent Location Tracking:
- Determines agent location before recommendation window (from previous task, geo-history, or home)
- Determines agent location after recommendation window (next scheduled task or home)
- Supports territory planning with start/end-of-day locations

- Travel Duration Calculation:
- Bulk API calls to calculate travel distances/durations
- Supports multiple map vendors or straight-line estimates
- Caches calculated data to avoid redundant API calls
- Handles tasks with `ignore_travel` flag

- Time Window Validation:
- Validates agent can travel to task and complete work within shift
- Considers work parameters (travel outside work hours, overtime allowance)
- Accounts for task spacing between assignments
- Validates against current time (no past recommendations)

* * *

### 5. Work Schedule & Shift Management

#### `TaskRecommendationFSMUtil`:

- Agent Schedule Integration:
- Retrieves agent work schedules and shifts
- Supports both standard FSM scheduling and WFO (Workforce Optimization) logic
- Validates recommendation windows against agent availability

- Work Parameters:
- Travel outside work hours permission
- Overtime allowance and limits
- Post-shift maximum overtime

- Time Range Adjustment:
- Adjusts recommendation windows to fit within agent shifts
- Handles past time corrections
- Enforces maximum 12-hour recommendation windows

* * *

### 6. Response Generation

`TaskRecommendationResponseGenerator`:

- Generates detailed recommendation responses with:
- Estimated travel duration to each task
- Expected start time for each task
- Work duration calculations
- Integration with Agent Efficiency plugin for dynamic duration estimates

`TaskRecommendationFSMPostFilterProcess`:

- Post-filtering logic for:
- Fixed Window Constraints: Overlaps recommendation window with task fixed windows
- Access Hours: Validates tasks against location access hour schedules
- Work Duration Validation: Ensures sufficient time for task completion

* * *

### 7. Query Refinement & Task Filtering

`TaskRecommendationFSMQueryUtil` (referenced but not in update folder):

- Refines queries with FSM-specific conditions:
- Tasks in "Pending Dispatch" state
- Tasks with valid locations (non-empty)
- Assignment group matching
- Dispatch group validation
- Window start/end time overlaps

* * *

### 8. Mobile Integration

- Service Graph components for mobile UI

- Quick actions for task recommendations

- Parameter screens for mobile input

- Write-back actions for recommendation acceptance

- UI rules and button configurations

* * *

### 9. Agent Efficiency Integration

- Dynamic work duration calculation based on agent efficiency metrics

- Recommendation criteria for efficiency-based ranking

- Integration with `sn_agent_effcy` and `sn_fsm_agent_effcy` plugins

* * *

### 10. Administration & Configuration

- Navigation Modules (in Field Service application):

1. Task Recommendation Policies - Configure recommendation policies
2. Recommendation Criteria - Manage filter and ranking criteria
3. Task Recommendation Applicabilities - Define when recommendations apply
4. Task Recommendation Properties - System properties configuration

- System Properties:
- Geo-routing calculation method
- Use of geo-history for agent location
- Rejection technician duration settings
- Other FSM-specific recommendation settings

* * *

### 11. Key Technical Capabilities

- Batch Processing: Handles multiple tasks and agents efficiently

- Data Caching: Reuses calculated travel/location data across batches

- Extensibility: Leverages extension points for customization

- Plugin Integration: Works with FSM Task Bundle, Agent Efficiency, Access Hours, Territory Planning

- Error Handling: Comprehensive validation with user-friendly error messages

- Logging: Dedicated logger (`TaskRecommendationLogger`) for debugging