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:

1. Authenticating a security user
2. Calling the Framework API
3. Retrieving agent records
4. 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.