x-caracal documentation
Important for users who upgraded their PBX to WMS 6.03 and higher!
After the upgrade, you need to set ACL rule "Can use x-caracal" for all users who need access to x-caracal as by default the access is forbidden.
On this page, you can find documentation about x-caracal–the Wildix ACD Stats that provides you with all the data you need to stay in control of your business.
Created: March 2021
Updated: May 2025
Permalink: https://wildix.atlassian.net/wiki/x/RQHOAQ
- 1 Datasheet
- 2 Introduction
- 3 Requirements
- 4 Activation
- 5 Deactivation
- 6 Reports
- 6.1 Setup
- 6.2 Filter
- 6.3 Search
- 6.4 Events
- 6.5 INFO Fields
- 7 Realtime
- 7.1 Queue Summary
- 7.2 Agent Status
- 8 Distribution Reports
- 9 Answered Reports
- 10 Unanswered Reports
- 11 Agent Reports
- 11.1 Agent Summary
- 11.2 Agent Availability
- 11.3 Pause Detail
- 11.4 Call Disposition by Agent
- 11.5 Full Agent Report
- 12 Scheduled reports
- 13 Custom Settings
- 14 Debugging
Introduction
x-caracal is the light, agile and effective ACD stats solution that provides you with all the data you need to stay in control of your business. ACD stats enable businesses to measure their sales performance, improve the customer service levels, and take data-driven decisions.
Unlike other ACD stats, x-caracal is:
Light: browser-based and cloud-hosted, no installation is required
Agile: provides you with constant feedback on the quality of your customer interactions and what needs to be improved
Effective: fully integrated into the Wildix communication system, and monitors all agents’ devices including mobile.
x-caracal is a built-in Business Intelligence tool that helps you minimize time-wasting activities and focus on increasing customer satisfaction and sales.
Requirements
WMS 6.0X or higher
1 Premium subscription (for the manager) + a minimum of 10 Business/ Premium subscriptions (for the agents) in case of Legacy Collaboration / Collaboration 7 or:
1 x-bees-SuperBee (for the manager) + a minimum of 10 x-bees-Standard/SuperBee subscriptions(for the agents) in case of x-beesCloud or Virtual PBX
Recurrent fee per each PBX (both for standalone PBXs and in case of WMS network)
ACL rule set for all users who need access to x-caracal:
prior to WMS 6.03: ACL rule "Can use CDR-View"
starting from WMS 6.03: ACL rule "Can use x-caracal"
Notes:
At least 1 Premium and at least 10 Business subscriptions are required for the activation
Each user with Premium subscription gets access to x-caracal
Only call events generated by users with Business/ Premium subscription are logged by x-caracal (each call agent needs at least a Business subscription)
1 Premium subscription allows you to monitor up to 50 call queues (Call groups)
Virtual PBX requirements:
minimum: 2vCPU, 2GB RAM
recommended: 2vCPU, 4GB RAM or higher, depending on number of users/ load
MYSQL server to set up x-caracal database
MYSQL v. 5.7 or higher (or MariaDB v. 10.2 or higher)
MYSQL user should have Database-specific privileges to be able to create, read, update, delete the database
The following mods shouldn't be used on MYSQL server: ONLY_FULL_GROUP_BY, NO_ZERO_IN_DATE, NO_ZERO_DATE
Don't create the Database manually, with the specifics permissions to create, it is automatically done during x-caracal initialization.
To open x-caracal in x-bees/ Collaboration 7, go to Analytics -> next to Analytics at the top of the page, click More -> select x-caracal
Documentation: x-bees documentation, Collaboration 7 Documentation.
Activation
To activate x-caracal, you need to purchase a dedicated service fee in Salesforce Partner Community and then enable x-caracal in WMS.
Note: If you have previously requested x-caracal activation, you only need to take Step 1.
Take the following steps to proceed with the activation:
Step 1. Purchase x-caracal in Salesforce Partner Community
Access Salesforce Partner Community
Choose the necessary Project (for information on how to create and manage projects, check out the Projects section of the Salesforce Partner Community Guide)
On the Project page, click the Create Quote button:
Note: For Customers with already active PBX license, you need to create Change Order Project (for details, check out the guide Change Order and Fast Change Order Process in SFPC). Once created, click Create Quote in the Change Order Project.
When filling out Quote details, in the General Questions section, in Additional Configuration field, make sure to select License Upgrade:
In the License Upgrade section, select Yes in front of x-caracal:
Fill out other Quote sections and proceed with the Quote creation
Create Order from the Quote and confirm it (please follow instructions from the guide How to Create Quote and Confirm Order in Salesforce Partner Community)
Note for VM/HW PBXs: you can purchase and activate x-caracal service only on Virtual PBX, it cannot be activated on Hardware PBX.
Step 2. Enable x-caracal in WMS
Cloud PBX activation
To activate the service on Cloud PBX, proceed with the step described below.
Go to WMS Settings -> PBX -> Integrations
Proceed to Analytics tab
Tick off Enable checkbox
Click Save
Virtual PBX activation
To activate the service on Virtual PBX, proceed with the step described below.
Virtual PBX limitations
x-caracal settings are not reset when:
resetting PBX to factory defaults
restoring from backup
Go to WMS Settings -> PBX -> Integrations
Proceed to Analytics tab
Tick off Enable checkbox and connect to MYSQL server by entering Host, Database name and credentials to set up x-caracal database
Notes:
The following characters are not supported in credentials: $ and #
Click Save
After x-caracal is activated, you can access it from Legacy Collaboration -> Other (expanded) -> x-caracal:
Deactivation
It is possible to deactivate x-caracal on the WMS side:
Important: Deactivating x-caracal removes both x-caracal service and all its data.
Go to WMS -> Settings -> PBX -> Integrations
On the Analytics tab, disable the checkbox in front of the Enabled button under x-caracal and click Save:
Click Delete on the pop-up window that appears to confirm your decision:
Reports
Reports are divided into 5 groups:
Realtime - real-time statistics by Queue/ Agent
Distribution - call distribution reports by day/ week/ hour/ day of week
Answered - detailed information and reports regarding answered calls
Unanswered - detailed information and reports regarding unanswered calls
Agent - detailed information and reports regarding each Agent activity
Setup - settings for assigning specific Agents/ Queues to other users for monitoring
There are also Search option that helps you to find information about any specific call and Filter to display statistics for a subset of Queues and Agents.
All reports can be downloaded in 4 different formats:
Currently the following statistics are not included into the reports:
no outgoing calls
no call recordings
no tags
Note regarding clearing of old data: by default, the system clears data older than 12 months, if other values are not specified in WMS -> Settings -> PBX -> Call and chat history. Clearing of old data is run at 4 am every day.
Documentation: WMS Settings Menu - Admin Guide: Call and chat history
Setup
Note: This menu is available only for a manager who is a user with "Admin" user type.
Starting from WMS 6.04.20230724.1, Setup -> Schedules/Alerts menu is available for non-admin users too (see section Scheduled reports).
This menu allows a manager to assign specific Agents/ Queues to other users that they can monitor (see below instructions) and schedule reports (see section Scheduled reports).
All users with Premium subscriptions are displayed on this page and are automatically synced every 15 minutes. If you need to display any changes immediately, click Sync button.
To assign specific Agents/ Queues, proceed with the following steps:
Go to Setup -> Users:
Select a supervisor and click Pencil icon to edit a record:
Select Agents/ Queues that this user can monitor:
Click Save
Current limitations:
1. Users need to log out/ in to Legacy Collaboration after a manager applies changes
2. User names are not automatically updated after they are changed in WMS -> Users. To display updated user names:
launch the Sync manually or wait 15 minutes for the changes to be synced automatically
reload Users page in x-caracal
Filter
Before proceeding to reports, choose a subset of Queues and Agents to display statistics for. Date range and time frame also need to be specified.
Once the selection is done, you can get the reports by clicking Display report and navigating to the desired tab.
Notes:
The selected date/ time range is very important. All report data that you run are related to this date/ time range. So, it is possible to look at all reports for any given date/ time specified.
Example; daily report, weekly report monthly report, or even reports for a portion of the day such as 9am until noon. This allows you to evaluate distribution and performance over any given date/ time. In addition, some reports can be grouped by periods (e.g. daily, weekly, etc). So, it’s possible to select a date/ time range of the entire year, then group by week. This is a very useful approach to see trends over long periods.
Depending on the PBX load, the following limits for maximum allowed days range apply when generating reports:
Less than 500K records - max 180 days
500K - 700K records - max 120 days
700K - 900K records - max 60 days
900K and more - max 31 days
Note: It is possible to set custom limit using custom config parameter. Documentation: Custom config parameters List - x-caracal
Search
Search helps you quickly locate records you are interested in. You can apply several filters at the same time.
Date: a date range can be specified to filter out calls
Queue: specify Queue name/ ID
Agent: if you are interested in info related to certain Agent, type Agents name/ extension
Event: when you are particularly interested in certain event, filter by event
Wait Time: search for calls that were waiting X amount of time
Talk time: filter calls that lasted X amount of time. This is useful for finding calls that took too long or perhaps that did not last long enough. Both conditions are possible indicators of issues
Number: If all you have for a certain call you are interested in is the caller id number, that is all you need
Events
When a call enters the system, it generates several events indicating its status. Below you can find the list of common events:
Event | Description |
ABANDON | A caller hung up before being answered |
COMPLETEAGENT | A caller was connected to an agent, and the call was terminated normally by the agent |
COMPLETECALLER | A caller was connected to an agent, and the call was terminated normally by the caller |
COMPUTED END PAUSE | Emerges if there is no end pause event, for example, if an agent goes from being in a pause state to being available without a pause event being triggered. In this case, the system will compute this event starting from the last event of the pause period. For example, an agent goes into a break at 5 pm, and there is no pause event recorded when the break ends; the computed end pause will be recorded at the same time as the next event received |
COMPUTED END SESSION | Emerges if there is no end session, eg, for static members because they don't log off. In such case, the system computes this event starting a session from the last event of the day. For example, an agent takes a break at 5 pm so the computed start session will be recorded at 5 pm |
COMPUTED START PAUSE | Emerges if there is no start pause event, for example, if an agent goes from being available to being in a pause state without a pause event being triggered. In this case, the system will compute this event starting from the first event of the pause period. For example, an agent goes into a break at 12 pm, and there is no pause event recorded at that time; the computed start pause will be recorded at 12 pm. |
COMPUTED START SESSION | Emerges if there is no start session, eg, for static members because they don't log in. In such case, the system computes this event starting a session from the first event of the day. For example, an agent answers a call at 9 am, so the computed start session will be recorded at 9 am |
CONNECT | A caller was connected to an agent |
END CALL COMPLETEAGENT | A call was hung up by an agent |
END CALL COMPLETECALLER | A call was hung up by a caller |
END CALL TRANSFER | A call transfer was completed |
END PAUSE | Shows when an agent switched back to Available from DND/ Away |
END SESSION | A session ends when a logoff or remove event is found |
ENTERQUEUE | A call has entered the queue |
EXITEMPTY | A caller was forcefully removed from the queue because there were no available agents and the queue was configured to do so |
EXITWITHTIMEOUT | A caller was removed from the queue because max. waiting time in the queue was reached |
FAILED | A call was offered but an agent didn't answer it as a result of RINGNOANSWER event. The event can repeat based on the timeout set for a call group. For example, there might be 4 FAILED events because the call was offered 4 times (4 "10 seconds ringing cycles" because the call group time out is 10 and the call can remain 40 seconds on the queue) |
REJECT | A call failed to connect to an agent |
RINGNOANSWER | A call was offered to the agent but it was not answered |
START CALL | Emerges when a call is answered by an agent |
START PAUSE | Shows when an agent is paused (means the agent is in DND or Away) |
START SESSION | A session begins when a login or add event is found |
TRANSFER | A call was answered by an agent and subsequently was transferred to a different extension |
INFO Fields
When you access the complete call flow details (under Detailed reports), you have up to 5 Info Fields, the meaning of each field depends on the event, here is a complete list of possible events and its info fields. Fields Info 4 and Info 5 are not applied.
Field | ABANDON/ EXITWITHTIMEOUT | COMPLETECALLER/ COMPLETEAGENT | CONNECT | ENTERQUEUE | EXITWITHKEY | RINGNOANSWER | TRANSFER |
Info 1 | Caller position at hung up/exit the queue | Waiting time | - | - | Wait time in seconds: how long the caller waited in the queue before pressing a key to exit | Ringing time | Transfer destination extension (transfer_exten): the phone number or extension to which the call was transferred |
Info 2 | Caller original position | Call length | Call unique id | Caller ID | Typically contains the position of the caller in the queue at the time they pressed the key to exit | - | Transfer destination context (transfer_context): Dialplan procedure in which the destination extension was dialed |
Info 3 | Waiting time | Caller original position in the queue | Ringing time | Position when entering queue | Contains the specific key that the caller pressed to exit the queue. This identifies which option the caller selected when they pressed a key to leave the queue | - | Contains the original Info 1 value as it was prior to the transfer. This usually stores the call's ring time in seconds |
Info 4 | N/A | N/A | N/A | N/A | N/A | N/A | Contains the original Info 2 value as it was prior to the transfer. Typically holds the call duration or other data from the COMPLETECALLER or COMPLETEAGENT event |
Info 5 | N/A | N/A | N/A | N/A | N/A | N/A | Contains the original Info 3 valueas it was prior to the transfer. Typically holds the caller's position in queue from the COMPLETECALLER or COMPLETEAGENT event |
Realtime
Realtime report shows your Queues and Agents real time state.
Queue Summary
The report shows the state of the selected Queues in real time.
Queue: ID/ name of selected Queues
Waiting: number of calls waiting in a queue
Agents: number of available Agents
Logged Off: number of Agents logged off from Queue
Busy: number of busy (in a call) Agents
Paused: number of paused Agents
Answered: number of answered calls
Unanswered: number of unanswered calls
Abandoned: number of calls abandoned by Caller in the selected Queues
Abandon Rate: ratio of abandoned calls over a period of time set in Filter
Avg Wait: Average Wait Time for all calls in the Queue, expressed in time
Avg Duration: Average Talk Time for all calls in the Queue, expressed in time
Max. wait time: Maximum Waiting Time for all calls in the Queue, expressed in time
Agent Status
The report provides information about Agents user statuses and status messages (status messages display is supported starting from WMS 6.01.20221122.1).
Queue: ID/ name of selected Queues
Agent: Agent name/ extension
State: Agent user status and status message (status messages display is supported starting from WMS 6.01.20221122.1)
Available - Agent is available
Ringing - there is an incoming call to Queue that Agent belongs to
Busy - Agent is in a call that belongs to Queue
Personal call - Agent has a personal call, not related to Queue
On pause - Agent is paused
On Hold - a call is on hold
Duration: the call's duration
Caller ID: number of Caller
Queue: the called number of the Queue
Priority: the priority when choosing Agent for a call. The value is constant which means all Agents have the same priority
Last in Call: the total time since Agent was in call
Calls: the total number of calls answered by Agent