Unless otherwise specified, in the case you are running a clustered system, you can have "default" settings and then separate settings for each machine in the cluster.

For example, if you are trying to read a configuration property called "my.prop" and you are on a cluster server called "alpha":

This is the "classic" locally-hosted QueueMetrics platform. Data can be stored on a flat-file, uploaded to the QueueMetrics database or read out Asterisk’s own tables. In order to perform actions on the PBX, the custom QueueMetrics dial-plan is required for all actions (Actions: Classic) or only for outbound dialing (Actions: DirectAMI).

This is the QueueMetrics-Live platform. Data is stored on the SQL database and is uploaded through Uniloader. Actions to be performed are sent back to Asterisk through the Uniloader and require custom dialplan added to the local PBX.

As there is no local audio storage, we suggest using a custom JSON audio recording platform for audio storage.

The Freeswitch platform is able to receive rewritten data from a Freeswitch / FusionPBX system. Each QueueMetrics system analyzes one single tenant.

The Enswitch platform is able to receive data from an Integrics Enswitch 3.14+ system, perform actions on the system and listen to audio recordings.

The MirtaPBX platform is able to receive data from a MirtaPBX system, perform actions on the system and listen to audio recordings.

The JSON API platform is able to control an external platform through a unified API.

This is the default platform for QueueMetrics and it is able to perform all QueueMetrics interactions to the PBX. Actions are executing by calling the 'extensions_queuemetrics.conf' dial-plan, that must be available on the target machine.

Depending on the target PBX, you may need to edit the supplied dialplan to use it.

Configuration

To turn it on you need to set:

Available actions are controlled in configuration.properties by setting:

Each action is controlled by a stanza in configuration.properties, for example to set call outcomes:

More details are availble in Enabling Agent’s page actions.

In this mode, actions are performed by queueing them and waiting for 'uniloader' to fetch and perform them. Actions are expressed as calls to the 'queuemetrics' dialplan, that needs to be available on the target PBX.

This platform is used in QueueMetrics Live to allow remote actions.

Configuration

To turn it on you need to set:

In DirectAMI mode, actions performed on the PBX do not require a piece of dial-plan to be included; QueueMetrics will connect directly to the AMI port of your Asterisk system (as determined by callfile.dir and its cluster.*.manager equivalents in cluster mode) and will perform the actions you require.

This mode is slightly less flexible than the dialplan-based Classic mode, but:

Tracking outbound

As it is not currently possible to originate outbound calls tracked by QueueMetrics without using the dialplan, if you need to do manual outbound you still need to include the custom ''extensions_queuemetrics.conf'' dialplan; QueueMetrics will then dial extension '28@queuemetrics' for manual outbound dialing.

Since Uniloader 0.4, it is possible to track outbound calls made by QueueMetrics without using the dialplan if you have outbound tracking enabled. This feature is not turned on by default and has to be set manually. This feature is at the moment experimental.

Configuration

To turn it on you need to set:

The following configuration options are available:

When running in cluster mode, you can have configuration that is specific for one single cluster member and it will override the general one - see Defining system properties for members of a cluster.

Examples

Example for a FreePBX system running without hotdesking enabled. The agent is logged on to the queue as "Local/XXX@from-internal", that is rewritten by QueueMetrics as "Agent/XXX", and matches a SIP extension with the same code. We specify a StateInterface so the queue is always aware of the state of the agent’s phone.

This is an example for a FreePBX system running with hotdesking enabled. The agent is logged on to the queue as "SIP/YYY" but appears in QM as "Agent/XXX" and a proper hotdesking record is written to match the two entities.

This is an example for a FreePBX system running with hotdesking enabled but without dialplan. Uniloader must be running in "tracker" mode with "outbound" enabled.

Some Notes on Spying

When spying, QueueMetrics always tries to connect the supervisor to the agent’s channel. If the live agent channel appears under a different name from the one used to create it (e.g. if the agent channel was a Local/XXX@ctxt that has been optimized to SIP/XXX), then you need to supply the parameter platform.directami.optimizedagentchannel in order to let QueueMetrics find the correct agent channel to spy on.

When spying, you can try different settings of platform.directami.spyoptions to configure additional behavior. The following options are added automatically:

In DirectAMI Live, DirectAMI calls are not performed immediately but stored on the AMI queue and then performed by Uniloader on the receiving server. This means you can have the advantages of DirectAMI (no dialplan included for most use cases) on remote systems where actions are proxied by Uniloader.

Configuration

To turn it on you need to set:

All other configuration options are the same as DIRECTAMI.

With the Freeswitch actions module, commands are sent to Freeswitch’s 'mod_callcenter' though the ESL API.

As in FusionPBX the id of 'mod_callcenter' agents is a UUID, it is important to configure all agents so that their UUID is set in the 'External reference' field. A list of agents with their UUIDs can be obtained by running uniloader pbxinfo fusionpbx.

Configuration

To turn it on you need to set:

The following configuration options are available:

Examples

Example for a FusionPBX system running at address 192.168.7.5:

In Freeswitch Live, Freeswitch API calls are not performed immediately but stored on the AMI queue and then performed by Uniloader on the receiving server.

Configuration

To turn it on you need to set:

All other configuration options are the same as FREESWITCH.

Examples

This example is for a system where Uniloader and Freeswitch are running on the same machine. Please note that the ESL address is relative to Uniloader.

This platform lets you control an arbitrary external system that implements a very simple JSON API. This way, QM can control any PBX system, and it is often used to interact with cloud providers that "abstract away" the specific PBX API.

For each interaction request, a simple JSON stanza like the one below is sent to an HTTP/s end-point you define as a parameter called cmd, using either HTTP POST or GET.

QueueMetrics expects no specific answer to the call, as long as it succeeds with an HTTP status 200, as any requested action will be reflected in the queue_log data being uploaded.

Configuration

An example configuration might be like the one below:

The meaning is:

Actions

You will usually implement either AGENTLOGIN/AGENTLOGOUT or ADDMEMBER/REMOVEMEMBER-style presence for your agents.

JSON request details

In the JSON request, fields have the following meaning:

When parsing the JSON request, you can expect all the fields above to be present, and must accept any other fields that may be added to the request in the future. The JSON block has always the same shape, and unused parameters for the current action are set to null.

The Enswitch actions module will connect over HTTP/HTTPS to an existing Enswitch 3.14+ system and perform actions.

The following actions are supported:

Configuration

To turn it on you need to set:

The following configuration options are available:

To listen to audio recordings, you also need to turn on the EnswitchPlatformListener (see Pluggable Listener for the Enswitch platform).

Selecting chanspy vs barge-in

As QueueMetrics has only one "spy" action available, the choice of whether it is a "normal" spy or a barge-in depends on the number you enter as your local extension.

If the extension is prefixed with a "!", then a barge is attempted using the default prefix defined in platform.enswitch.bargePrefix; otherwise the prefix specified in platform.enswitch.spyPrefix is used.

Prefixes are set as in the Features → Feature prefixes menu of your Enswitch system.

Open and Closed log-on modes

The default integration mode for Enswitch uses a "closed" log-on mode; this means that QueueMetrics cannot log an arbitrary agent on to Enswitch, but will basically toggle the pause status of an existing agent, albeit logging the event "as if" it was a real log-on/log-off or a pause/unpause event.

Weird as this sounds, this means that an administrator can configure with certainty which agents are supposed to work on a queue, and end-users cannot change them - they can just toggle them on and off.

If you set platform.enswitch.openLogons=true, a log-in will instead mean that an extension with the same agent code and dtype=phone will be added to the queue, with a priority as defined on the QM queue definition. A log-off will remove such extension from a queue.

Outbound mode

In order to use outbound, you need to create a special extension prefix that will take a few digits for the queue id and then the number to be dialled, for example let’s say our prefix is *787, then tree digits for our queue, then the number to be dialled - e.g. eg *787 146 123456 will dial number 123456 on queue 146.

Then queue 146 must be a real Enswitch (inbound) queue, that we will use as a placeholder to make sure that only active agents (currently logged on, not puased), can actually dial out.

Agents will then:

When this happens, a call is sent to the agent’s phone; as soon as they pick it up, a second leg to the callee is dialled and all queue log events are to be recorded in real-time as the call progresses.

The outbound call is displayed on the agent’s panel as it happens, and also on the real-time screen. As the agent need to be logged on to an outbound queue to make an outbound call, there is no risk of misalignment between their log-in status and calls made; and the queue will be existing in Enswitch (though not actually used to process incoming calls).

Also, from the real-time page and the wallboard, it is possible to start a chanspy of such an outbound call.

A possible configuration could be:

Note how the $Q placeholder allows adding the queue id within the outbound prefix. This also allows having only one default outbound queue, by not adding the placeholder in the generated number.

For example, if you are dialling number 1234 on queue 101 with platform.enswitch.dialoutPrefix set to…​

Generated queue_log

When QueueMetrics works with Agent/1234 on Enswitch:

Therefore it is important in the agent definition that your agent be called Agent/1234 with an alias of SIP/1234@enswitch so that it will work properly.

Another difference in generated queue_log is that the PAUSEALL verb will appear not just once but for all queues, that might in turn emit a local pause event. This causes no problem to QueueMetrics, and is caused by the fact that any log entry on Enswitch must belong to an existing queue. So you may see duplicated records at the same time-stamp.

The MirtaPBX actions module will connect over HTTP/HTTPS to an existing MirtaPBX system and perform actions.

The following actions are supported:

Configuration

To turn it on you need to set:

No dialer is available, all dialer actions are turned off.

QueueMetrics is able to connect to a WombatDialer instance to schedule calls.

This must be provided in the form of four system parameters (that can be set in the Edit System Parameters page).

This is the standard search method that comes with QueueMetrics. Basically, all directories under default.monitored_calls are explored recursively, and all audio files matching the Asterisk ID of the main call that was queued are retrieved. Therefore the call files found can be zero or more.

This PM is sub-optimal for very large call centres, where the cost of scanning through all recordings (maybe on remotely mounted disks) could take a significant time. If you are in such an environment, see the LocalFilesByDay entry.

This PM is used by default if no other server is specified in the configuration.properties file.

This PM works exactly like the LocalFiles one, but allows using placeholders in the file path; this way, you can set the default recordings directory to handle only a subset of all recordings.

For example, if you set default.monitored_calls to /var/myrecordings/%YY-%MM/ when trying to listen to a call that was made on Jan 9, 2007 will expand to /var/myrecordings/2007-01/ therefore making the directory scanning much more manageable.

Valid placeholders include:

Though this is unlikely, it is possible that a call gets recorded on a given day and then gets queued on a different day, e.g. for calls that happen around midnight. QM handles this case by double-checking all calls within a boundary of n hours from the midnight in both the days that are divided by that midnight. This behaviour can be set using the audio.lookBack property.

Asterisk can easily adapt to recording files in a way that is compatible with this storage model, like e.g.:

Will store audio files as:

The nice part is that Asterisk will automatically create missing directories, as needed.

This is the standard XML-RPC implementation and makes it easy to create a completely custom scheme to handle recordings. The output of this function must be a single URL that can either stream the audio file or launch a player to stream that call. This is completely user-configurable.

The details of how to write an XML-RPC server for the QMAudio.findStoredFile interface can be found on the XML-RPC guide for QueueMetrics. We ship a sample implementation of such a server in the xmlrpc_audio_server.php server that comes with QueueMetrics.

See also section Enabling XML-RPC call listening and streaming.

This PM lets you offline all the audio recording to an Oreka system - see http://oreka.sourceforge.net/

This PM lets you playback audio (and optionally video) of recorder calls stored in Oreka. In order to listen to live calls, it is possible to use either some Asterisk-based method, e.g. ClassicQMListenerRT below, or an Oreka-based methos like OrekaWebRT below.

It needs the JDBC URI to point to the Oreka database; the database must contain the following tables: orktag, orksegment, orktape, orkservice, orktagtype.

This PM is an advanced version of the OrekaWeb module, and it offers the same functionalities plus a few additional ones:

The same set-up instruction apply as per the OrekaWeb PM.

This PM lets you query multiple PMs in the order you specify to look for the call you are looking for. A common scenario may be the following one:

In order to retrieve calls, we want QM to first check in /queues/audio; if nothing is found, then we will look under /mnt/nas/2010-11-23. This can be implemented with the following configuration:

What we do here is the following:

If you use MultiListener within a cluster, and you the cluster has members s1 and s2, you should use a configuration like the following one:

If you want, you could use the same folder for recordings of both servers (though it is better to keep them separate to speed-up access); still, they have to be specified for all servers in the cluster.

Exposed Interface

QueueMetrics expects to have in his classpath an implementation of the following interface:

The getUrls should return a matrix containing the list of URLs associated to the specified callID. Each row in the matrix specifies:

To make sure QueueMetrics looks for your recordings on your CallCabinet online repository, five parameters must be set.

And you must make sure that the recordings are saved on CallCabinet with the CustomerInternalRef field set to the Asterisk Unique ID of the call used by QueueMetrics.

Go to Edit System Parameters and edit the following parameters:

Make sure you replace the "xxxx" characters with your Customer ID, Site ID and API Key. The audio.html5player=true parameter lets us to listen to the recordings directly on our browser.

Go back to the HomePage and take a look at any report containing some of the calls that are recorded.

Clicking on the Call Detail Icon (the magnifying glass icon on the right), will show at the bottom that QueueMetrics retrieves the recordings related to that call’s Call ID (Asterisk Unique Call ID).

The name format QueueMetrics uses to represent a recording is the following:

DateTime_agent_queue.mp3

Clicking on the Play icon just right of the recording name will stream the recording directly without downloading it.

To download it instead, one must click on the recording name.

This listener is able to retrieve and download calls through the Enswich 3.13+ API. Shares its configuration with the Enswitch Actions module.

To find a call, it goes looking for all the calls recorded that are "around" the time of beginning of the call to be retrieved, so e.g. with a margin of one hour, it starts searching one hour before the beginning of such call and ends two hours (two times the margin) after the beginning.

The width of this "margin" is controlled by platform.enswitch.audioSearchMargin - on busy systems, it might be advisable to set it to a lower value (e.g. 1000 seconds) as to avoid retrieving hundreds or thousands of calls.

This listener is able to retrieve and download calls through the MirtaPBX API. Shares its configuration with the MirtaPBX Actions module.

This listener will query an external server, sending in a JSON payload thet identifies the call and expecting a result for each media file that is attached to it. If there are no recordings, the server is expected to return an empty list of results.

What this module does is:

The payload that is sent us similar to the one below - it is sent as parameter query of a web form - this way the same semantics is used for both GET and POST forms (though POST has a content-type of application/x-www-form-urlencoded):

That is interpreted as:

And the results must be a list of zero or more JSON objects, like the below:

For each object:

Allowed type tags are:

This is the standard QM behaviour: when listening to inbound or outbound calls, a popup appears and asks for a local extension. That local extension is connected to the live channel so that the local user can listen to the ongoing call.

In order for this to work, the dial-plan on each Asterisk server must implement the correct logic - an example is given in the [queuemetrics] context that comes with QueueMetrics.

This PM is used by default if no other server is specified in the configuration.properties file.

This is the standard XML-RPC implementation and makes it easy to create a completely custom scheme to handle live monitoring. The output of this function must be a single URL that will launch a player to stream that call. This is completely user-configurable.

The details of how to write an XML-RPC server for the QMAudio. listenOngoingCalls interface can be found on the XML-RPC guide for QueueMetrics. We ship a sample implementation of such a server in the xmlrpc_audio_server.php server that comes with QueueMetrics.

See also section Enabling XML-RPC call listening and streaming

This PM lets your supervisors monitor agents using a web-based interface provided by Oreka. The supervisors will simply click on a live call and it will be streamed to them through their browser (note: a window will open and will close immediately before the popup opens. This is expected behaviour).

In order for this PM to work, your system configuration must matche these criteria:

Do not forget to set the oreka.web property in any case in order to download the playback applet.