Prev   Next

3. Understanding call parameters

There are three methods exported by the XML-RPC interface, and they are used for three different reasons:

3.1. The method QM.stats

This is the main method exported, its XML-RPC name being QM.stats. It takes a number of arguments, all of which must be supplied and must have the correct data type. They are:

  1. (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.
  2. (String) Access username: this one must be the user name of an active user holding the key ROBOT.
  3. (String) Access password: this must be the clear-text password of the given user name
  4. (String) Logfile - always leave blank.
  5. (String) Period - always leave blank.
  6. (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).
  7. (String) End of period. Same format as start of period
  8. (String) Agent filter - an agent’s name, like "Agent/101" that must be the filter for all the relevant activity
  9. (List) A list of the required analysis 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 at 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.

3.2. The method QM.realtime

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:

  1. (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.
  2. (String) Access username: this one must be the user name of an active user holding the key ROBOT.
  3. (String) Access password: this must be the clear-text password of the given user name
  4. (String) Logfile - always leave blank.
  5. (String) Agent filter - an agent’s name, like "Agent/101" that must be the filter for all the relevant activity
  6. (List) A list of the required analysis 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]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, it’s 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 the sum of all agents associated to all elementary queues composing the macro queue, even if the macro queue has directly assigned agents.

3.3. The method QM.qareport

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:

  1. (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.
  2. (String) Access username: this one must be the user name of an active user holding the key ROBOT.
  3. (String) Access password: this must be the clear-text password of the given user name
  4. (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).
  5. (String) End of period. Same format as start of period
  6. (String) Agent filter - an agent’s name, like "Agent/101" that must be the filter for all the relevant activity
  7. (String) The form name for wich you need to have information
  8. (String) The grader type used to filter out graded forms. It could be any of the following values: "unknown", "agent", "grader", "caller". This parameter is optional and could not be present in the function call
  9. (List) A list of the required analysis 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.

3.4. The method QM.qaformreport

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:

  1. (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.
  2. (String) Access username: this one must be the user name of an active user holding the key ROBOT.
  3. (String) Access password: this must be the clear-text password of the given user name
  4. (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).
  5. (String) End of period. Same format as start of period
  6. (String) Agent filter - an agent’s name, like "Agent/101" that must be the filter for all the relevant activity
  7. (String) The form name for wich you need to have information
  8. (String) The grader type used to filter out graded forms. It could be any of the following values: "unknown", "agent", "grader", "caller". This parameter is optional and could not be present in the function call
  9. (List) A list of the required analysis 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.

3.5. The method QM.qaformsummary

This method is very similar to QM.stats but it’s used to retrieve aggregated information about a specific Quality Assessment Form. It must be called with the following parameters:

  1. (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.
  2. (String) Access username: this one must be the user name of an active user holding the key ROBOT.
  3. (String) Access password: this must be the clear-text password of the given user name
  4. (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).
  5. (String) End of period. Same format as start of period
  6. (String) Agent filter - an agent’s name, like "Agent/101" that must be the filter for all the relevant activity
  7. (String) The form name for wich you need to have information
  8. (String) The grader type used to filter out graded forms. It could be any of the following values: "unknown", "agent", "grader", "caller". This parameter is optional and could not be present in the function call
  9. (List) A list of the required analysis 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.

3.6. The method QM.qaformgrading

This method lets you fill a QA form through an RPC-XML call. It replies with the same raw information reported by the QM.qaformreport method and could replace it if QA parameters are empty when calling.

  1. (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.
  2. (String) Access username: this one must be the user name of an active user holding the key ROBOT.
  3. (String) Access password: this must be the clear-text password of the given user name
  4. (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).
  5. (String) End of period. This is at least the number of seconds the call was in the waiting status (or the complete call time or a suitable number that comfortably contains the call like, for example, 3600).
  6. (String) The form name for wich you need to have information
  7. (String) The unique identifier for the call to be graded
  8. (String) The grader type used to filter out graded forms. It could be any of the following values: "unknown", "agent", "grader", "caller". This parameter is optional and could not be present in the function call
  9. (Struct) The list of QA items score supplied as (string,string) pairs. The list should contain all specific form items codes and their relative score. In order to specify N/A values for not mandatory items, an empty string should be specified. If the list is left empty, no QA score will be filled into the form
  10. (List) A list of the notes to be filled in the form. Each note must be supplied as a String. If the list is empty, no new comments will be added to the form.
  11. (List) A list of the required analysis 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.

String queues, String user, String pass, String t_from, String t_to, String formName, String agent, HashMap constraints, ArrayList requestedItems)

3.7. The method QM.qacallstograde

  1. (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.
  2. (String) Access username: this one must be the user name of an active user holding the key ROBOT.
  3. (String) Access password: this must be the clear-text password of the given user name
  4. (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).
  5. (String) End 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).
  6. (String) The form name for wich you need to have information
  7. (String) Agent filter - an agent’s name, like "Agent/101" that must be the filter for all the relevant activity
  8. (List) A list of constraints used by the engine to filter out all relevant forms (see below for the correct syntax)
  9. (List) A list of the required analysis to be returned to the client. Each analysis name must be supplied as a String.

The constraints are a set of (key, values) pairs used by the engine to filter out the calls to be graded. The constraint list should be defined with the proper syntax in order to be correctly interpreted by QueueMetrics.

There are two types of constraints: the percentage values and the absolute values. They should be respectively specified through the suffixes "min" or "num".

The constraints are related to different categories:

  • Individual agents: specified through the key AXG (like, for example: AGX_min or AGX_num)
  • All calls: specified through the key AC (like, for example: AC_min or AC_num)
  • Outcome code: specified through the key outcome followed by the outcome code and separated by an underscore character (like, for example: outcome_KN_num or outcome_KN_min)
  • Agent group: specified through the key agroup followed by the agent group name and separated by an underscore character (like, for example: agroup_Default_min or agroup_Default_num)

3.8. The method QM.auth

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:

  1. (String) User name
  2. (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.

3.9. The method QM.authenticate

This method is used to obtain the profile of a user given its login and password. The profile is made up of both login and - where applicable - agent information. It is possible to obtain the profile either of the very user you are calling (by knowing its login and password) or of a "deferred" separate user, if you have a user that would have the admin keys to view that information in the main GUI.

The deferred username works so that:

  • If a deferred username is passed, and

  • If the username/login pair are valid and the user has key USRADMIN and ROBOT

    • Then the User.* output for the deferred user is returned
    • If the user also holds the key USR_AGENT, the Agent.* output is returned as well
  • The password-change function applies only to the user who logs in, not to the deferred user.

Call parameters

  1. (String) User name
  2. (String) Deferred user name, or blank
  3. (String) Password
  4. (String) New password, or blank if you do not want it changed.

Response

There is only one response block returned, named "output", where the caller will retrieve all user data, including the live key set for that user.

The output block has the format:

Column 0 Column 1 Explanation

user.user_id

173

Internal user-id

user.login

Agent/101

user.real_name

John Doe

user.class_name

AGENTS

user.keys

USER AGENT XX YY

All computed keys, space-separated

user.n_logons

37

user.last_logon

2011-10-08 12:34:56

user.comment

Optional

user.token

876543

Optional

user.email

me@home.it

Optional

user.enabled

true

"true" or "false"

agent.id

86

Internal agent-id

agent.description

Agent J.D. (101)

The name displayed in reports

agent.aliases

A set of aliases (if present)

agent.location

Main

Blank if none

agent.group_name

Experienced agents

Blank if none

agent.current_terminal

Sip/1234

Blank or "-" if none

agent.vnc_url

http://1.2.3.4/vnc

Optional

agent.supervised_by

Demoadmin

Blank if none, or login of the supervisor

agent.xmpp_address

xmpp:101@myserver

XMPP chat address

agent.visibility_key

Optional

agent.payroll_code

Optional

password.changed

OK

OK if password was changed, blank otherwise

The following rules apply:

  • Column zero contains the attribute
  • Column one contains the value of the attribute (we supply a sample in the table above)
  • Attribute names are not case sensitive
  • If the user is also an agent, that is, there is an agent under the same name as the login, Agent attributes are passed.
  • Blank attributes may or may not be present in the list of attributes

3.10. The method QM.findAudio

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:

  1. (String) User name (*)
  2. (String) Password (*)
  3. (String) Server
  4. (String) Asterisk-ID (*)
  5. (String) Call start (integer timestamp)
  6. (String) Agent
  7. (String) Queue

The username and password of a 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 a 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.

3.11. The method QM.insertRecordTag

This method is used to associated a new tag for a specific recording call file. This method could be used to retrieve the list of tags related to a specific call.

Call parameters:

  1. (String) User name (*)
  2. (String) Password (*)
  3. (String) Server: the server name in a cluster setup or empty for a not cluster setup
  4. (String) AsteriskId: the asterisk specific call id
  5. (String) FileName: the recording filename associated to the tag to be inserted
  6. (String) Time: the time (in seconds) where the tag will be placed. If empty, the tag will be placed at the beginning of the file
  7. (String) Duration: the tag duration (in seconds). It could be empty.
  8. (String) Message: the tag message. If empty, no tags will be added. This is useful for retrieve the list of tags associated to a specific call.
  9. (String) Color: an hex color value in RGB form to be associated a tag. (from 000000 to FFFFFF)

Response

There is only one response block returned, named "TagRecords", where the caller will retrieve the list of tags associated to the specific server and AsteriskId parameters.

3.12. The method QM.tskAddNote

This method is used to insert a note task to a particular user. It’s possible to specify the validity start and end date.

Call parameters:

  1. (String) Access username: this one must be the user name of an active user holding the key ROBOT.
  2. (String) Access password: this must be the clear-text password of the given user name
  3. (String) Task to user: this is the login to the user where the task should be addressed
  4. (String) Start of validity: 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). It could be empty.
  5. (String) End of validity: 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). It could be empty.
  6. (String) Task Process Field: This is an optional identifier defined as ProcessFamily/ProcessId to be associated to the task. Either ProcessFamily and/or ProcessId could be empty. The field could be empty.
  7. (String) Task message: This is the message associated to the task
  8. (String) Task notes: This is the optional note associated to the task

Response There is only the result response block. No other custom blocks will be returned as a result.

3.13. The method QM.tskAddTraining

This method is used to insert a training task to a particular user. It’s possible to specify the validity start and end date, a title and an optional URL or ID that will be shown in the task detail page.

Call parameters:

  1. (String) Access username: this one must be the user name of an active user holding the key ROBOT.
  2. (String) Access password: this must be the clear-text password of the given user name
  3. (String) Task to user: this is the login to the user where the task should be addressed
  4. (String) Start of validity: 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). It could be empty.
  5. (String) End of validity: 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). It could be empty.
  6. (String) Task Process Field: This is an optional identifier defined as ProcessFamily/ProcessId to be associated to the task. Either ProcessFamily and/or ProcessId could be empty. The field could be empty.
  7. (String) Task message: This is the message associated to the task
  8. (String) Task notes: This is the optional note associated to the task
  9. (String) Task Training Title: This is an optional task training title.
  10. (String) Task URL: This is an optional URL (in the http://www.mydomain.com/path format) to be associated with the training task. It could be empty.
  11. (String) Task ID: This is an optional ID associated to the task. If an URL if defined by the previous parameter, this field will be ignored. It could be empty.

Response There is only the result response block. No other custom blocks will be returned as a result.

3.14. The method QM.tskAddMeeting

This method is used to insert a meeting task to a particular user. It’s possible to specify the validity start and end date, a title, a date and an optional duration that will be shown in the task detail page.

Call parameters:

  1. (String) Access username: this one must be the user name of an active user holding the key ROBOT.
  2. (String) Access password: this one must be the clear-text password of the given user name
  3. (String) Task to user: this is the login to the user where the task should be addressed
  4. (String) Start of validity: 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). It could be empty.
  5. (String) End of validity: 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). It could be empty.
  6. (String) Task Process Field: This is an optional identifier defined as ProcessFamily/ProcessId to be associated to the task. Either ProcessFamily and/or ProcessId could be empty. The field could be empty.
  7. (String) Task title: This is the title associated to the task
  8. (String) Task message: This is the message associated to the task
  9. (String) Task date: This is the meeting date. 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).
  10. (String) Task duration: This is the optional meeting duration. If no duration is specified (or specified as 0) the meeting will have an undefined duration.
  11. (String) Task notes: This is the optional note associated to the task

Response There is only the result response block. No other custom blocks will be returned as a result.

3.15. The method QM.setActivationKey

This method is used to remotely change the configuration key of the QueueMetrics instance or to query the current configuration key.

As this operation is potentially critical, the user sending this request must hold the keys ROBOT and KEYUPDATE. We ship such a user named ’keyupdater’ in the default QM configuration but it has to be manually enabled. Make sure you change the password as well.

As the system must be restarted after setting the new key so that it is picked up (this is done automatically), the QM server may be unavailable for a few seconds during the restart phase and current user sessions may be forcibly terminated. It is therefore not advisable to run this command on a busy system with many users logged in.

Call parameters:

  1. (String) Access username: this one must be the user name of an active user holding the keys ROBOT and KEYUPDATE.
  2. (String) Access password: this must be the clear-text password of the given user name
  3. (String) New key: this is the key that must be set. If blank, the current parameters are reported.

Response

The custom block "KeyResults" is filled with the following parameters:

  • KEY_status : NOKEY if no new key is given, otherwise OK or ERROR depending on the success of the operation
  • KEY_plexId : The server identifier
  • KEY_message : A message explaining what went wrong
  • KEY_current_appl : The name of the application
  • KEY_current_user : The name of the user that the application is licensed to
  • KEY_current_exp : The expiration date for the current key

Please note that when a new key is installed, the current user and expiration date are those of the system on which the key is being installed; you should get the new ones as soon as the system restarts (will usually take between 5 and 20 seconds).

3.16. The method QM.broadcastMessage

This method is used to insert broadcast messages that will be shown in the realtime broadcast message page.

Call parameters:

  1. (String) Access username: this one must be the user name of an active user holding the key ROBOT.
  2. (String) Access password: this must be the clear-text password of the given user name
  3. (String) Message text: the text message to be broadcasted
  4. (String) Queue Name: the optional queue name (it could be empty)
  5. (String) Location Name: the optional location name (it could be empty)
  6. (String) Supervisor Login: an optional supervisor login (it could be empty). The message will be broadcasted to people reporting to the supervisor login.
  7. (String) Agent Login: an optional agent login (it could be empty). The message will be addressed to the specified agent.
  8. (String) forEveryone: this could be "true" or "1" for messages to be broadcasted to everyone; "false" or "0" otherwise.

Response There is only the result response block. No other custom blocks will be returned as a result.

Prev   Next
 Home