There are three methods exported by the XML-RPC interface, and they are used for three different reasons:
- QM.stats: get the main historical stats
- QM.realtime: get the real time stats (available since QM 1.3.5)
- QM.qareport: get the Quality Assessment statistics (available since QM 1.6.0)
- QM.qaformreport: get some Quality Assessment Forms details (available since QM 1.6.0)
- QM.qaformsummary: get Quality Assessment statistics related to same form (available since QM 1.6.0)
- QM.auth: use QueueMetrics as an auth server for third party software (available since QM 1.3.5)
This is the main methods exported, its XML-RPC name being QM.stats. It takes a number of arguments, all of which must be supplied and all of which must have the correct data type. They are:
- (String) Queue name or names: the set of queues that must be include in the analysis. They must be separated by a "|" symbol if more than one queue is passed. The queue name is the internal Asterisk queue name.
- (String) Access username: this one must be the user name of an active user holding the key ROBOT.
- (String) Access password: this one must be the clear-text password of the given user name
- (String) Logfile - always leave blank.
- (String) Period - always leave blank.
- (String) Start of period. This must be written in exactly the format yyyy-mm-dd.hh.mm.ss (do not forget the dot between the date and the hour).
- (String) End of period. Same format as start of period
- (String) Agent filter - an agent’s name, like "Agent/101" that must be the filter for all the relevant activity
- (List) A list of the required analyses to be returned to the client. Each analysis name must be supplied as a String.
This call will start up a session in QueueMetrics, check if the user exists and has the privilege to run the report, run the analysis, prepare the required results and return them. At the end of the call, the QueueMetrics session is destroyed so no data is kept for further elaboration.
This means that it’s usually the most efficient thing to do to request all needed response information and once, but it’s wise to limit yourself to the minimum data set you will actually need, as each block takes up CPU and memory space to be marshaled between the native Java format, the intermediate XML format and the resulting client format.
It is also advisable to run large data set analysis at night time or when nobody is accessing the system, as they may take quite a lot of RAM and CPU, and this may slow down QueueMetrics for the other live users.
This method is very similar to QM.stats but it is used to retrieve the real time stats. It must be called with the following parameters:
- (String) Queue name or names: the set of queues that must be included in the analysis. They must be separated by a "|" symbol if more than one queue is passed. The queue name is the internal Asterisk queue name.
- (String) Access username: this one must be the user name of an active user holding the key ROBOT.
- (String) Access password: this one must be the clear-text password of the given user name
- (String) Logfile - always leave blank.
- (String) Agent filter - an agent’s name, like "Agent/101" that must be the filter for all the relevant activity
- (List) A list of the required analyses to be returned to the client. Each analysis name must be supplied as a String.
The same suggestions that are given for QM.stats apply.
![[Important]](../images/icons/important.png){kind=icon} | Important |
|---|---|
Please note that there is a difference between results produced by the XML rpc realtime calls and the realtime statistics produced through the QueueMetrics GUI when the key realtime.members_only is equal to true. The difference is related to the agents list shown. Being the list of queues, in the XML RPC call, specified by a list of names instead of a list of queue unique identifiers, is not possible to correctly identify elementary queues from macro queues having the same name. In this situation the agent list will always be calculated as sum of all agents associated to all elementary queues composing the macro queue, even if the macro queue has directly assigned agents. |
This method is very similar to QM.stats but it’s used to retrieve Quality Assessment statistics. It must be called with the following parameters:
- (String) Queue name or names: the set of queues that must be included in the analysis. They must be separated by a "|" symbol if more than one queue is passed. The queue name is the internal Asterisk queue name.
- (String) Access username: this one must be the user name of an active user holding the key ROBOT.
- (String) Access password: this one must be the clear-text password of the given user name
- (String) Start of period. This must be written in exactly the format yyyy-mm-dd.hh.mm.ss (do not forget the dot between the date and the hour).
- (String) End of period. Same format as start of period
- (String) Agent filter - an agent’s name, like "Agent/101" that must be the filter for all the relevant activity
- (String) The form name for wich you need to have information
- (List) A list of the required analyses to be returned to the client. Each analysis name must be supplied as a String.
The same suggestions that are given for QM.stats apply.
This method is very similar to QM.stats but it’s used to retrieve raw information about Quality Assessment Forms. It must be called with the following parameters:
- (String) Queue name or names: the set of queues that must be included in the analysis. They must be separated by a "|" symbol if more than one queue is passed. The queue name is the internal Asterisk queue name.
- (String) Access username: this one must be the user name of an active user holding the key ROBOT.
- (String) Access password: this one must be the clear-text password of the given user name
- (String) Start of period. This must be written in exactly the format yyyy-mm-dd.hh.mm.ss (do not forget the dot between the date and the hour).
- (String) End of period. Same format as start of period
- (String) Agent filter - an agent’s name, like "Agent/101" that must be the filter for all the relevant activity
- (String) The form name for wich you need to have information
- (List) A list of the required analyses to be returned to the client. Each analysis name must be supplied as a String.
The same suggestions that are given for QM.stats apply.
This method is very similar to QM.stats but it’s used to retrieve aggregated information about a specific Quality Assessment Forms. It must be called with the following parameters:
- (String) Queue name or names: the set of queues that must be included in the analysis. They must be separated by a "|" symbol if more than one queue is passed. The queue name is the internal Asterisk queue name.
- (String) Access username: this one must be the user name of an active user holding the key ROBOT.
- (String) Access password: this one must be the clear-text password of the given user name
- (String) Start of period. This must be written in exactly the format yyyy-mm-dd.hh.mm.ss (do not forget the dot between the date and the hour).
- (String) End of period. Same format as start of period
- (String) Agent filter - an agent’s name, like "Agent/101" that must be the filter for all the relevant activity
- (String) The form name for wich you need to have information
- (List) A list of the required analyses to be returned to the client. Each analysis name must be supplied as a String.
The same suggestions that are given for QM.stats apply.
This method is used to authenticate a username / password couple against the QueueMetrics server. This can be used by third-party software that does not want to keep its own separate user database but wants to use QueueMetrics’ instead.
Call parameters:
- (String) User name
- (String) Password
Response
There is only one response block returned, named "auth", where the caller will retrieve all user data, including the live key set for that user.
This method is used to retrieve a recorded file name from the QueueMetrics server. In order to retrieve the file name QM will invoke the currently configured Pluggable Modules to search within the current recording set. This can be used by third-party software that needs to retrieve audio recordings via HTTP.
Call parameters:
- (String) User name (*)
- (String) Password (*)
- (String) Server
- (String) Asterisk-ID (*)
- (String) Call start (integer timestamp)
- (String) Agent
- (String) Queue
The username and password of an user with ROBOT access are mandatory.
If QM is on a clustered setup, the Server parameter must be passed to qualify the Asterisk call-id.
The Asterisk-Id is mandatory and is the one retrieved in the Call Details blocks.
Some PM may optionally require the Call start, Agent and Queue parameters; those are used for fuzzy matching of calls, e.g on an external storage. Most PMs that do an exact match do not need those parameters.
Response
There is only one response block returned, named "AudioFiles", where the caller will retrieve the filename of each recorded file and an URL to actually download the file.
The response may include zero or more files; it is well possible that multiple recordings be present for one call.
A sample PHP file that shows how to access the findAudio interface is supplied with QueueMetrics.