Legacy Pipeline Atlas worker-1snapshot 2026-07-15

MDClarity · task primitive

WorkqueueAssignment

Overview

WorkqueueAssignmentTask assigns items (accounts or visits) to workqueue stacks based on configured assignment criteria. The task evaluates all enabled WorkqueueAssignmentCriteria, searches for matching items using the criteria's search terms, creates ordered item stacks, and optionally removes items from workqueues that no longer match the criteria.

Use this task when: You need to populate workqueues with accounts or visits that match specific search criteria, typically as a scheduled job to keep workqueues up-to-date.

Don't use this task when:

Parameters

Parameter Type Required Default Description
CriteriaKey string No null The key of a specific WorkqueueAssignmentCriteria to process. If null or empty, all enabled criteria are processed.

Execution Flow

YesNoNoYesNoYesYesNoYesNoStartWorkqueueAssignmentGet Criteria ListCriteriaKey provided?Get Single CriteriaGet All CriteriaCriteria found?Log No Criteria MessageExitLoop Through Each CriteriaCriteria.Enabled?Log Disabled MessageCriteria.AutoUnassign?Get All Possible ItemsGet or Create Workqueuesfor AssigneesBuild Remove ListUnassign Items fromWorkqueuesLog UnassignmentActivitiesLog AutoUnassign FalseSearch for Matching ItemsMore Criteria?Create Item Maps with SortOrderSave Items to Criteria StackLog New and RemovedItemsLog Completion

Usage Examples

Example 1: Process all enabled criteria (scheduled task)

var task = new WorkqueueAssignmentTask
{
    // CriteriaKey = null by default - processes all enabled criteria
};
// Run this as a scheduled job (e.g., daily at 3 AM) to keep all workqueues current

Example 2: Process a specific criteria after configuration change

var task = new WorkqueueAssignmentTask
{
    CriteriaKey = "WAC-12345" // Only process this specific criteria
};
// Use when a specific criteria was modified and needs immediate refresh

Example 3: Initial workqueue population

// First, create the WorkqueueAssignmentCriteria in the database
var criteria = new WorkqueueAssignmentCriteria
{
    Key = "HighValueAccounts",
    Name = "High Value Accounts Queue",
    Enabled = true,
    Type = WorkqueueEntityType.Account,
    AutoUnassign = true,
    ViewType = WorkqueueType.Standard,
    FetchSize = 1,
    SortBy = "Service Date",
    SortDirection = "DESC",
    Assignees = new List<string> { "[email]", "[email]" },
    Criteria = new List<SearchTerm>
    {
        new SearchTerm("Account Status", "Open"),
        new SearchTerm("Balance", "> 5000")
    }
};
criteriaRepo.Save(criteria);

// Then run the assignment task
var task = new WorkqueueAssignmentTask
{
    CriteriaKey = "HighValueAccounts"
};
// This will create workqueues for both assignees and populate them

Related Tasks Comparison

Task Use Case Manual vs Automatic Scope Item Removal
WorkqueueAssignment Populate workqueues based on search criteria Automatic (scheduled) All or specific criteria Controlled by AutoUnassign flag
Manual Assignment (UI) Ad-hoc item assignment Manual Single items Not applicable
Workqueue Fetch (UI) Retrieve items from existing stack Manual User-triggered Items remain in stack

Performance Considerations

Database Impact

Optimization Tips

Scenario Recommendation Rationale
Many criteria (10+) Run as nightly batch job Avoids running during business hours when users are actively working
Large item counts (10K+) Use specific CriteriaKey when testing Reduces scope during development/debugging
AutoUnassign = true Expect additional overhead Requires fetching all possible items twice (once with status filter, once without)
Custom property sorting Ensure custom property filters are present Task automatically adds filters for custom property sorts to improve performance
High-volume criteria Monitor ActivityLog growth Each assignment/unassignment creates activity logs

Important Notes

Error Handling

The task uses a continue-on-error approach with comprehensive logging:

// From Assigner.cs - logs errors but continues processing other criteria
foreach (WorkqueueAssignmentCriteria criteria in criterias)
{
    if (criteria.Enabled)
    {
        logger.Log($"Processing criteria: {criteria.Name} ({criteria.Key})");
        // ... processing logic ...
    }
    else
    {
        logger.Log($"Enabled set to false for criteria: {criteria.Name} ({criteria.Key}).");
    }
}

Important Error Behaviors:

Common Error Scenarios:

Common Pitfalls

Issue Problem Solution
Items not appearing in workqueue Items are in the stack (WorkqueueCriteriaItemMap) but not fetched to workqueue This is expected behavior - users must "fetch" from the UI to pull items from stack to their workqueue
AutoUnassign removes items immediately Items removed from workqueue as soon as they no longer match criteria Set AutoUnassign = false if you want items to remain in workqueue once assigned
Duplicate workqueues for users Multiple workqueues created for same user/criteria combination Known issue (TODO in code) - currently uses .First() to handle this
Performance degradation with many criteria Task slows down with 20+ criteria Run during off-hours, or use CriteriaKey to process specific criteria incrementally
Custom property sorts fail Sort by custom property doesn't work Ensure the custom property is also included as a filter in the criteria search terms
Items never removed from stack Old items remain in WorkqueueCriteriaItemMap indefinitely Ensure AutoUnassign is enabled, or manually clear stacks before reassignment
ActivityLog table growth ActivityLog table grows large over time Implement archival or retention policy for ActivityLog records

Code References