AgentList Action in NICE CXone Desktop Studio
The AgentList action in NICE CXone is used to retrieve detailed information about agents configured in a business unit. This action returns agent profile details in an array format and helps administrators, supervisors, and developers automate workflows based on agent information. A single agent using AgentID All agents within the business unit Team and supervisor information Agent email and login details Custom profile fields This action is commonly used in: Workforce automation Dynamic routing Supervisor workflows Reporting scripts Validation processes Email/SMS notification systems In summary, the AgentList Action in NICE CXone is essential for effective agent management. This functionality enhances productivity by streamlining agent data retrieval processes through the AgentList Action in NICE CXone. Understanding the AgentList Action in NICE CXone The AgentList Action in NICE CXone plays a crucial role in integrating with various workflows. The AgentList action communicates with the NICE CXone Framework API and returns agent profile information as an array. It can: Check if an agent is active Retrieve email addresses Find supervisor details Identify team memberships Access custom user fields Validate login information AgentList Workflow Diagram How AgentList Works The action works by: Authenticating a security user Calling the Framework API Retrieving agent records Returning the data into an array variable Basic Flow SetSecurityUser ↓AgentList ↓Agents Array Output ↓Use Data in Script Logic Important Dependency Before using AgentList, you must configure: SetSecurityUser Action The SetSecurityUser action authenticates the request using a user’s security permissions. Mandatory Requirement The output variable from SetSecurityUser must match the SecurityUser input property in AgentList. Example: SetSecurityUser Output = SecurityUserAgentList SecurityUser = SecurityUser If this dependency is missing, the action will fail. Supported Script Types AgentList supports multiple script types inside Desktop Studio. Supported Channels Script Type Supported Generic Yes Email Yes Chat Yes Phone Yes Voicemail Yes Work Item Yes SMS Yes Input Properties 1. Caption Used to identify the action on the Studio canvas. Example Get Agent Details 2. SecurityUser This property stores the authenticated security object returned from SetSecurityUser. Example SecurityUser No curly braces are needed. 3. AgentID Used when retrieving information about a specific agent. Example {agentId} If left blank, the action returns all agents in the business unit. Output Properties ListVar (out) Stores returned agent data as an array. Default Variable Agents AgentList Output Fields The action returns a large set of agent profile details. Standard Fields Returned Field Description AgentID Unique agent identifier FirstName Agent first name LastName Agent last name UserName Login username Email Agent email address TeamId Team identifier TeamName Team name IsActive Indicates active status IsSupervisor Indicates supervisor role LastLogin Last login timestamp Location Agent location BusinessUnitID Business unit identifier InternalId Internal system ID Supervisor Information Fields AgentList can also return reporting hierarchy details. Field Description ReportToId Supervisor ID ReportToFirstName Supervisor first name ReportToMiddleName Supervisor middle name ReportToLastName Supervisor last name Custom Fields The action supports custom attributes configured in CXone. Field Custom1 Custom2 Custom3 Custom4 Custom5 These can store business-specific values such as: Department Employee type Shift information Region Skill group Common Use Cases 1. Check Agent Active Status You can verify whether an agent is currently active. Example IF Agents[0].IsActive = True Used in: Workforce validation Dynamic routing Login monitoring 2. Retrieve Agent Email Useful for automated notifications. Example Agents[0].Email Used in: Escalation emails Supervisor alerts Automated workflows 3. Identify Team Membership Retrieve team-based routing information. Example Agents[0].TeamName Used in: Team routing Department filtering Skill assignment workflows 4. Supervisor Identification Fetch reporting manager information. Example Agents[0].ReportToFirstName Useful for escalation workflows. Result Branch Conditions AgentList supports branching logic. Default Branch Executed when the action completes successfully. OnError Branch Executed when: Authentication fails API connectivity issues occur Syntax problems exist Permissions are missing The system populates: _ERR with the error description. Error Handling Workflow Example Studio Script Logic Retrieve All Agents SetSecurityUser ↓AgentList ↓FOR EACH Agent IN Agents ↓Process Data Retrieve Specific Agent AgentID = {agentId} Returns only the requested agent record. Benefits of AgentList Centralized Agent Information Provides complete agent profile details from a single action. Dynamic Workflow Automation Enables scripts to make routing decisions based on: Team Supervisor Active status Location Custom attributes Reduced API Complexity Instead of multiple API calls, AgentList consolidates information retrieval. Best Practices Always Use SetSecurityUser This is mandatory for authentication. Handle Errors Properly Always configure the OnError branch. Use Specific AgentID When Possible Fetching a single agent improves performance. Store Outputs Efficiently Since the response is an array, loop carefully through results. Related Framework API Actions Other useful actions related to AgentList include: Action Purpose All Agent Skill Assignments Retrieves agent skills Agent States V4 Retrieves agent states Get Agents List Returns agent collections Get Agent Details by Agent ID Detailed agent lookup Real-Time Business Scenarios Workforce Monitoring Check which agents are active before assigning tasks. Intelligent Routing Route interactions based on team or location. Automated Notifications Send emails to agents or supervisors dynamically. Supervisor Escalations Identify reporting managers automatically. Conclusion The AgentList action in NICE CXone Desktop Studio is a powerful Framework API action that retrieves agent profile information dynamically inside Studio scripts. It supports automation, routing intelligence, workforce visibility, and supervisor-based workflows. By combining: SetSecurityUser AgentList Array processing Error handling organizations can build scalable and intelligent CXone automation solutions-NICE CXone Training.
AgentList Action in NICE CXone Desktop Studio Read More »








