Create AgentWork Records for External Routing

The external routing application creates AgentWork records to route work items to a rep in Omni-Channel.

We strongly recommend not to use external routing and Omni-Channel routing simultaneously because they may assign the same work item to the same rep.This conflicting assignment could lead to complications while tracking consumed work capacity.

Note

When the partner routing application receives new PendingServiceRouting creation events (where the routing type equals External), it uses the values in the event notification to determine what work needs to be routed to a rep. It makes a routing decision by creating AgentWork records. This API is existing functionality that partners use to query Salesforce.

The partner routing application uses these steps to generate and send the AgentWork records:

Creates an AgentWork record using the IDs, such as the PendingServiceRouting ID and WorkItem ID, gathered from the PendingServiceRouting event notification. Keep track of the PSR ID and the WorkItem ID as they are required for creation of the AgentWork record.
Stores the AgentWork records in the external routing application until they are ready to be routed to a rep.
Executes Apex code to send the ready AgentWork record to Salesforce.

This Apex code sample creates an AgentWorkrecord and assigns the work item to a specific rep.

1AgentWork work = new AgentWork();
2work.ServiceChannelId = '<ServiceChannelId>';
3work.WorkItemId = '<WorkItemId>';
4work.UserId = '<UserId>';
5work.PendingServiceRoutingId = '<PendingServiceRoutingId>';
6work.CapacityWeight = <Capacity Weight from PSR>;
7insert work;

Transferring Work to a Specific Rep

When your routing requirements necessitate that work be directed to a specific rep rather than a queue, you can utilize the Preferred User functionality. This is particularly useful for maintaining continuity in customer service or handling high-priority escalations.

How it Works

To transfer work to a specific support rep, turn on Skills-Based and Direct-to-Agent Routing in Omni-Channel settings. Once these settings are enabled, when a Pending Service Routing (PSR) record is generated, the system populates a specific field to signal the routing engine:

Field: PreferredUserId
Logic: The external routing engine should prioritize the ID found in this field.
Outcome: Instead of following standard load-balancing or queue-based logic, the engine attempts to assign the AgentWork record directly to the specified UserId.

Ensure your external routing engine is configured to check for the presence of a PreferredUserId on the PSR record before executing its standard distribution algorithms. If this field is populated, it should override the default queue routing to ensure the work reaches the intended rep.

Note

Omni-Channel Developer Guide

Create AgentWork Records for External Routing

Transferring Work to a Specific Rep