In the following example:

Extensions.conf

Queues.conf

Make sure that you do not forget the explicit timeout when calling the Queue() command from extensions.conf, or queue timeouts will not be logged by Asterisk and therefore not reported by QM. A patch that corrects this Asterisk behaviour can be found at http://bugs.digium.com/view.php?id=5422 .

The URL should be embedded in the Queue() command as prescribed by Asterisk:

This command launches the queue "myqueue" and launches the webapp located http://site/app passing the following parametrs:

Please note that, for Asterisk version 1.4 and greater, the ${CALLERID} variable has been replaced by ${CALLERID(num)} or ${CALLERID(all)}.

The URL will appear on a clickable link on the Agent’s page.

If you set the property realtime.agent_autoopenurl to true, whenever the Agent’s page is reloaded, the most recent unopened URL is launched automatically.

AddQueueMember is a command that lets you add dynamic agents to a queue. Its main advantage is that you can add channels, i.e. terminals, so you’ll have most of the advantages of agents without the performance and stability problems that the agents module may cost in very large systems.

Its disadvantage is that it does not log the agent login/logoff to the queue_log, and so programs that analyze the queue log data like QueueMetrics will not see agents logging on and off. This is a major organizational problem in a real-world call center, where tracking agent logons and logoffs is vital to the smooth running of the operations.

The answer is to add a fake queue_log data for each logon and logoff. For QM, it is important to avoid multiple logoff lines and to compute online permanence with logoffs.

To do the adding, you dial 422XX, where XX is your local extension; the same happens with 423XX to be logged off.

With this setup, we verified that the queue_log can be analyzed by QueueMetrics and the dynamic agent shows up fine (albeit with the name of a terminal, like SIP/23, instead of the usual Agent/23 string, but you can modify it in QM itself).

This setup might even be used in a call center where agents are not actually used but queues connect straight to terminals to "fake" agent logon/logoff, in order to have such data available for reporting.

Standard Asterisk queues are, by definition, inbound queues; they accept a number of incoming calls, let them wait in line and distribute them to various agents based on the queue logic.

To make it possible to analyze outbound calls with QM, we added the concept of a "campaign" or "outbound queue", that is a set of calls made by different agents that are working for the same purpouse. Of course there is no such thing as an outbound queue in Asterisk, so we have to run a special piece of dialplan or an AGI script to produce the same information on queue_log for outbound calls as it is automatically produced for inbound queues.

As this only regards the actual Dial(…​) statement that Asterisk runs, it is possible to have different sources of numbers to be dialled by agents on outbound queues; they might enter the number on their keypad, or use the telephone, launch them from the Agent’s page or maybe use a predictive dialler for the task. QueueMetrics does not care, as long as the correct events are logged.

To get the AGENTATTEMPT code to work, it is necessary to patch the Asterisk module called app_queue.c in order to track down the required information. In order to perform this task, you must be confident with general Unix project patching and recompiling. It is advisable that Asterisk be shut down before applying the patch.

In order to apply the patch, just copy the file app_queue_agentattempt.patch found under WEB-INF/README/ to the apps/ directory of your Asterisk project, and then issue the following statement:

As long as you see no errors, the patching process worked successfully. It’s now time to rebuild the app by issuing a general make statement from the main Asterisk directory.

Restart Asterisk and check that the queue system is still working fine.

To see if the patch was correct, try dialling a queue and see that Asterisk writes AGENTATTEMPT records to the queue_log file.

QueueMetrics starts to analyze AGENTATTEMPT verbs when the configuration key default.ignoreRingNoAnswer is set to true.

Asterisk 1.4 is natively able to produce the RINGNOANSWER log entry that servers the same purpose of AGENTATTEMPT, so no patching is necessary. In this case QueueMetrics reports in the realtime page the last agent that had not picked up the phone when ringing. QueueMetrics starts to analyze RINGNOANSWER verbs when the configuration key default.ignoreRingNoAnswer is set to false.

Is possible to have the AGENTATTEMPT information in a not patched Asterisk 1.4 with some modifications in the dialplan. This option is limited to people not using the hotdesking feature. For more information on that, please refer to the QueueMetrics advanced configuration manual.

In order to implement this feature, QueueMetrics follows the following steps:

To enable unattended audio monitoring for inbound calls, you’ll have to edit the Asterisk dial-plan in order to include the [queuemetrics] context.

To enable unattended call monitoring for outgoing calls as well, you’ll have to set the piece of dial-plan referenced by the callfile.outmonitoring…​ properties.

Outgoing calls placed though queueDial.agi will usually be listened to by attaching to the local SIP/XXX or Local/XXX channel of the calling agent and not to the standard Agent/XXX channel used for inbound, so a different piece of dial-plan will be used. Note that in order for QueueMetrics to reference the outgoing calls, you must tell it that queue direction is Outgoing.

See also Appendix B: The [queuemetrics context] for an example of implementing Asterisk code for inbound and outbound call monitoring.

It is possible to use different PMs to handle different live audio - see Listening to calls using Pluggable Modules (PM).

To enable VNC monitoring you will first need a VNC server that is running on each client’s machine and that will serve the current layout.

You will also have to create a web page with a VNC client that may accept a VNC URL and show a VNC client (there are a number of Java-based VNC clients that can be displayed as an applet).

Configure the VNC URL as something like: http://myserver/vncpage.php?ip=192.168.3.17

Where the PHP page will connect the VNC applet to the server located on address 192.168.3.17

Make sure that your users hold the MON_VNC key in order to be able to access this feature.

As an alternative, we have some clients that use a simpler setup with each machine having their own copy of UltraVNC - http://ultravnc.sourceforge.net/ - and each machine running a web server with the locally-configured Java viewer. The VNC url is then the address of the local machine; when a person connects to it, s/he is asked for a password and then the screen is displayed through a Java applet. They report this setup to be very simple and working very well.

In order to enable actions on the Agent’s page:

As of QM release 12.10 it is possible to set input validation for both the agent code and the extension. As an example, by setting the key realtime.agentRegexp=1\\d\\d you are defining that the agent code must start with a one and cannot be more than 3 digits, while by setting the key realtime.extensionRegexp=\\d\\d\\d\\0 you define that the agent extension must be four digits and must end with a zero. Please note that the backslash in the regexp has to be written as '\\' in the configuration properties.

It is possible to run remote audio monitoring of both completed and ongoing calls using third party monitoring tools, for example OrecX. As QueueMetrics has no way of knowing the internal details of such applications, we made it possible to call an external XML-RPC server (we offer a stub written in PHP, but it can be written in any language and reside on any server, as long as it uses an XML-RPC library) that will basically pass back to QM the URLs required to perform the required task.

In order to enable this, we first tell QueueMetrics to use the XML-RPC Pluggable Modules for both call listening and streaming:

The XML-RPC server will be set by setting its URL in a configuration property, like for example:

The server must implements three XML-RPC calls called:

To make implementer’s life easier, we provide a simple XML-RPC stub server under WEB-INF/mysql-utils/xml-rpc that can be used as a starting point: no need to handle the XML-RPC stuff, just change the results of the two supplied functions and data goes back to QueueMetrics.

A call tracking code is a code to be input by a user telling the status of a call, be it inbound or outbound. This status code is a string (though we suggest to use numeric status codes, in order to make it easy to input them using a telephone keypad) and may be input either when the call is ongoing or after a short while from its end.

The queue_log entry looks like the following one:

This will set the CALLSTATUS to "21" for the call which Call-ID is "1231.1" it may be an open call or it may be just terminated (see Updating past calls).

If it is not possible to force the Call-ID, a second version of the verb is available:

This has exactly the same meaning; the second Call-ID passed as a parameter will override the original one.

If you prefer, you may log the queue name instead of "NONE" field shown above; in any case QM will ignore this piece of information.

The following rules apply:

The agent may either be a fill "Agent/xxx" string or the valid name of an Asterisk channel. It is acceptable to use a generic channel name instead of the specific one, i.e. "SIP/123" and "SIP/123-abcd" are equivalent.

The sample [queuemetrics] context that comes with QueueMetrics can be used as a starting point to output such data.

A call feature code is a code to be input by a user telling the sub-status of a call, be it inbound or outbound. This feature code is a string and may be input either when the call is ongoing or after a short while from its end. Several call feature codes can be associated to a single call; QueueMetrics will count all the associated feature code. A feature code may have an optional free text associated with it.

The queue_log entry looks like the following one:

This will set the feature code to "36" for the call which Call-ID is "1231.1" it may be an open call or it may be just terminated.

A second version of the verb is available:

This has exactly the same meaning but the feature code contains a free text associated with it.

Feature codes can be removed from a call by mean of a trace added in the queue log:

This will remove the feature code "36" to the call with Call-ID is "1231.1". If no feature code "36" have been already associated with the call, QueueMetrics simply discards the trace.

The following rules apply:

The sample [queuemetrics] context that comes with QueueMetrics can be used as a starting point to output such data.

A pause reason code is a code to be input by a user telling the reason why a pause was started. It should be ideally input together with the decision to go on pause, though QueueMetrics will accept the code and will attach to the correct pause even if the pause is resumed, as long as no other pause is started. The reason code is a string - though we suggest to use numeric status codes, in order to make it easy to input it using a standard telephone keypad.

The format is the following one:

This will set the pause reason to "21" for the pause that is either going on or has just finished. If the code is input after over 30 minutes from the end of the last pause, it is discarded.

The following rules apply:

The sample [queuemetrics] context that comes with QueueMetrics can be used as a starting point to output such data.

Skills can be specified at any time before of after the call enters the queue but the suggested way is to have them immediately after the ENTERQUEUE verb as in:

In the example above, the call is queued on a queue called cpc with required skills DE>=90 and NET>70, so it could be a request for someone servicing internet support in German. Basically you just add an event for each required skill, and the level at which it is required. We do not need this information on connected/failed calls, as we assume that the routing is always correct.

The following rules apply:

It sometimes happens that Asterisk will not log the call termination records for a call; as QM is based on the logged events, a call missing the call closure log will linger on forever in the realtime screen (or at least the maximum time allowed by the …​) and will appear as Ongoing or Not answered yet in the historical reports.

Since version 1.4.5 of QueueMetrics, it is possible to manually close a call from either the historical reports or the real-time screen. In order for this to work:

When this is done, open calls on the reports will show a red scissor icon:

And the same will happen for the real-time screen:

By clicking on that icon, a popup will appear that will ask for the length the call should be closed to. This length refers to the wait duration if the call is not answered and the conversation time if the call is answered. It is possible to change that from the default 5 seconds by setting a configuration property.

If the call has already been closed in the meantime, or you’re doing this operation twice, QM will report that the call has already been closed.

In order to keep track of DNIS and IVR information that relates to each call, you have to write special records on the 'queue_log' file that QueueMetrics parses.

This is very easy to do, e.g. imagine you have a piece of dialplan where you are going to call queue 'q-sample' and you have the DNIS code in the 'MYDNIS' dialplan variable, and the sequence of keys pressed as 'MYIVR':

There is no predefined format for DNIS and IVR information; QueueMetrics just handles it as free-form text strings. It can be optionally decoded by creating values in the IVR and DNIS configuration pages.

You can output only one record, or both, or none, depending on what you need.

Some call centers require to report call set at the list level below campaign. This is frequently used for outbound campaings.

QueueMetrics searches TAG information on the queue log file. To enable Asterisk to place a TAG signature in the queue log a dialplan modification is needed. Below is an example on how this could be done, assuming you have the TAG code in the 'MYTAG' dialplan variable:

You can assign only one TAG for each call. If more than one TAG are assigned to a single call, QueueMetrics will discards all TAGs except the latest found in the queue log file.

Since the demise of AgentCallBackLogin, it has been hard to do "hotdesking" in Asterisk - that is, having agents that work on queues because of their competences and not because they are sitting at a given extension.

With QueueMetrics 1.6.1, hotdesking is very easy to implement and it has no downsides, because:

Requirements:

QueueMetrics is compatible with Asterisk 1.8 but you need to properly set it. The first requirement is related to a strange behavior found in Asterisk 1.8.0 and 1.8.1 that prevents Asterisk to properly log all queue activity until a a reload command is issued from the CLI. To fix this problem we had to change the code in the logger.c file found in the main subfolder present in the asterisk sources, near the line 396, in order to have something similar to what is listed below:

Then we had to rebuild asterisk and to reinstall it.

The next step is to replace the extensions_queuemetrics.conf file with the specific version for Asterisk 1.8. To do this, you need to copy the extensions_queuemetrics_18.conf replacing the one present into the asterisk configuration folder then reload the dialplan from the CLI. The extensions_queuemetrics_18.conf is targeted to Asterisk 1.8 with hotdesking enabled.

Starting from QueueMetrics 1.6.3 is possible to define priorities when logging agents in a specific queue. The priority associated to each agent is dependent on how the agent was configured in the queue (main, spill or wrap). This feature populates two new channel variables ${QM_AGENT_PRIOLBL} and ${QM_AGENT_PRIONUM} when AddQueueMember is called by extensions 25 and 35 in the queuemetrics context.

In QueueMetrics, it is posible to keep track of a set of "known numbers" through a specific editor as described in Configuring known numbers (VIP callers / blacklists)

For each number, we track:

A webservice - built to be easy to query from the Asterisk dialplan or through JSON - lets the user query whether the number exists and what to do with it.

Possible actions include:

Those actions are to be implemented at the Asterisk dialplan level.

The webservice is meant to be easy to interoperate with a standard Asterisk CURL call.

The page returns a response as text/plain that will be embedded in the dialplan variable res. The response is based on the following table:

'Notes'

The trivial format used in the response makes it possible to use the service using the command-line curl, or by using a trivial scripting language.

The "user" parameter is mandatory and requires a valid QueueMetrics username and password, separated by a ":". This is needed because the API will be publicly exposed. The user must hold the security key PBXAPI

In order to avoid security risks, the user should be custom-made and assigned to a class that only contains the key PBXAPI. This way the user will be able to log on to QM but will have no actual grants but logging off.

'Asterisk hashes'

When querying an Asterisk hash, the result is built as a string so that you can do:

to load the results from QM, and then parameter e.g. 'action' can be read as:

In order to avoid issues when returning data from QueueMetrics in the HASH format:

When querying each response separately, the response is instead UTF8.

QueueMetrics bases its reports on data generated from the Asterisk queue_log file; still, it sometimes needs to send commands to Asterisk in order to performs some actions, e.g. log on agents, or listen to live calls.

In order to perform such commands, two things are required:

For historical reasons, the default way QueueMetrics used to send commands was to generate Asterisk call files; now this method is obsolete and the correct one is to set-up an AMI connection.

In order to set up an AMI conenction, you have to set the following property like e.g.:

The AMI URL is in the following format: tcp:username:password@server:port

All three fields are mandatory. The password is sent over a clear-text TCP connection, so make sure to protect it using e.g. a VPN tunnel if it is to traverse public networks.

The configuration above should be matched by the configuration in Asterisk’s own manager.conf file, that should look like the following one:

In order to make testing easier, QueueMetrics includes a test tool that checks whether the current connection is working or not; see Checking an Asterisk Manager connection for details.

QueueMetrics allows to listen to recordings that are stored in an encrypted format. This works by invoking a custom-supplied filter that will decrypt the recording on-the-fly before QM streams it back to the user.

Since QueueMetrics 13.03, IVR information is tracked natively within QueueMetrics.

IVR information is different from queue information, as:

IVR tracking requires changes to the current dial-plan of Asterisk in order to track the required information. Such changes - detailed in section Implementing IVR tracking - are not complex to implement, and are implemented natively in the QueueMetrics module of FreePBX. So if you use a common Asterisk distribution, chances are you already have IVR tracking available.