QueueMetrics FAQ - Common problems and solutions

Here is a list of solutions to common problems encountered when running QueueMetrics. For complete information on how to set up QueueMetrics, please consult the User manuals. You may also want to have a look at the Installing QueueMetrics metanode on AstRecipes or to our own official QueueMetrics forum.

QueueMetrics reports

QueueMetrics real-time page

Configuring Agents

QueueMetrics installation

MySQL storage and QLoaderd

QueueMetrics configuration

Running outbound campaigns

Common QueueMetrics errors

MySQL-related issues

XML-RPC issues

Advanced configuration

Why aren't all reports showing up in my copy of QM?

If you updtate to a new version of QueueMetrics that includes new reports, or have new reports custom-developed for you and update your system, you will notice that they will NOT appear after upgrading QM with the old database. This is because the definitions for your existing reports do not include the new blocks that were just created.

In order to add the new blocks, do the following:

On the "add record page" enter:After saving, if you try running the report and select the chosen page, the new block will appear.

Error: Out of memory error - Tuning Java Memory

This error can manifest itself in a multitude of ways, the most common being an error stating:
Servlet.service() for servlet LowayTransactionController threw exception java.lang.OutOfMemoryError

The problem with Java memory is that it is fixed, i.e. Java will not automatically use free memory unless explicityly told to do so. The default maximum memory size for most JVMs is 64 megabytes maxiumum, and it is not much if multiple users are running multi-megabyte analyses in QueueMetrics.

To tell Tomcat to use more memory than the standard pool, you have to set an environment variable before starting it up:

This tells Java to start by using 256 megabytes and expand the memory pool as needed up to 512 megabytes. Please note that Java will not return memory back to the system memory pool, so the only way to reclaim memory is by restarting Tomcat (you could restart it nightly with a script). You should also set this in the /etc/init.d/queuemetrics startup file, so that it's set system-wide when QueueMetrics starts.

If you run into this error only occasionally and you run a version of QueueMetrics that is before 1.0, you may want toupdate QueueMetrics to the current version, as version 1.0 is two to four times as efficient in using memory than previous versions.A twofold increase of data density has also been achieved in version 1.4.x compared to versions 1.3.x.

A real-life example for a larger call-center using Sun JDK 1.6 may be the following set:

See http://java.sun.com/docs/hotspot/gc5.0/gc_tuning_5.html for more information on Java memory setting and monitoring.

Isf the error you get is actually "OutOfMemory: Unable to create new native thread", see this FAQ entry.

Detecting realtime timing issues

If you run MySQL storage, it is easy to check whether the time zone on the Asterisk server is correct:See also:

Repairing a MySQL database

It sometimes happens that if your database server crashes, you may find that:This sometimes happens even on systems that seemed to work fine for a long time.

In order to fix these issues, you should:

  1. stop MySQL - THIS IS EXTREMELY IMPORTANT
    /etc/init.d/mysqld stop
  2. check tables using myisamchk (use the same case as written here):
    myisamchk -c /var/lib/mysql/queuemetrics/*.MYI
  3. if any error is shown, repair tables:
    myisamchk -r /var/lib/mysql/queuemetrics/*.MYI
  4. after that, restart Mysql:
    /etc/init.d/mysqld start

Why do I get wrong agent names displayed?

In order for QM to work correctly, you should not have an agent name associated with an agent at the Asterisk level; in any case, that name should not contain spaces.

If in Asterisk you have a configuration like:

    myvoip*CLI> agent show
    123 (John Doe) available at '1234@from-internal' (musiconhold is 'default')

You should remove the agent name from agents.conf or from the realtime table where it is defined; you should make sure that the logging happens as Agent/123 for calls; the in QM you can configure a mnemonic name for the agent so that it apperas in the reports.

Updating the Java SDK

If you want to update the Java SDK you use to run QueueMetrics, it is very easy to do it.

Download and install a new version of Java SDK (from SUN, it's better - do not use GCJ).

You can install it anywhere on your system - like imagine you install it as/opt/java/jdk1.6.0b7.

As QueueMetrics accesses its own Java SDK under a symbolic link placed at /usr/local/queuemetrics/java, it is trivial to change that to use a different SDK.

    cd /usr/local/queuemetrics
    rm -f java
    ln -s /opt/java/jdk1.6.0b7 java
then restart QueueMetrics.

To check that the new Java is working, go to the License page and check the Java version that it is using.

Using UTF-8 encoding

QueueMetrics is a fully internationalized application: that is, it handles all user transaction with UTF-8 encodig, and therefore can display and accept any character for any language.

Unfortunately, MySQL does not natively use UTF-8 encoding for its tables and will try to use the "current encoding" whenever possible. So you may notice that if you e.g. enter an agent's name using not-Latin characters, when you read it back from disk it appears all garbled or a series of ??? signs.

To make QM fully able to process UTF-8 strings, you should follow the steps detailed here:

1. Run the following commands on all tables of the database but the queue_log table:

    ALTER TABLE `agaw_alarms` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `agaw_dati` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `agaw_logs` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `agaw_runs` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `agenti_noti` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `arch_classes` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `arch_syslog` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `arch_users` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `broadcast_msg` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `call_status` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `code_possibili` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `dbversion` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `locations` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `oq_calls` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `oq_notes` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `oq_queues` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `pause_codes` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `qa_data` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `qa_forms` CONVERT TO CHARACTER SET utf8;
    ALTER TABLE `qa_forms_items` CONVERT TO CHARACTER SET utf8;

If your system has other tables, please do the conversion on ALL tables.

2. Open the QueueMetrics web.xml and modify the connection string adding, before the </param-value> tag, the string:

    &amp;useUnicode=true&amp;characterEncoding=utf8&amp;characterSetResults=utf8
After this modification you should have something that looks like:
    <param-value>jdbc:mysql://127.0.0.1/queuemetrics?zeroDateTimeBehavior=convertToNull &amp;jdbcCompliantTruncation=false&amp;user=queuemetrics&amp;password=javadude &amp;useUnicode=true&amp;characterEncoding=utf8&amp;characterSetResults=utf8</param-value>

It must all be written on a single line.

3. Then download the latest MySQL java connector binary package you can find at the link:http://dev.mysql.com/downloads/connector/j/5.1.html
Extract the mysql-connector-java-5.1.7-bin.jar file and copy it on your QueueMetrics box, placing in the folder /usr/share/java.
Replace the symbolic link you can find in /usr/local/queuemetrics/webapps/queuemetrics-1.x.x/WEB-INF/lib in order to have it pointing to new connector.

4. Restart the QueueMetrics service issuing a /etc/init.d/queuemetrics restart

This will enable UTF8 support.

Updating QueueMetrics and keeping the key and configuration

When updating QueueMetrics, whether you do that manually or using yum, you need to copy web.xml and configuration.properties from the old installetion to the new one.

This is easy to do, as distinct QM applications are stored as:

So they are never deleted.

Before the upgrade, make a backup of the QM database; it may be updated by the QM updater on the first run, so it is better to have a copy - just in case.
After the upgrade, have a look at the WEB-INF/README/Updating.txt file - it shows the new parameters and the new security keys that you m,ay have to enable on an existing install in order to unlock the new functionalities.

See also:

Removing Tomcat logging

QueueMetrics keeps a detailed log of all transactions performed, in order to be able to find which transactions are slow and for forensic analysis (you can never know...). They may end up taking substantial disk space.

First, you may want to rotate Tomcat logs using a logrotate job like the following one:

    /usr/local/queuemetrics/tomcat/logs/*.* {
      missingok
      rotate 5
      daily
      compress
      create 0640 root root
      postrotate
          /etc/init.d/queuemetrics restart > /dev/null 2> /dev/null
      endscript
    }
If you want to turn off logging entirely, edit the server.xml file and change from:
    <Logger className="org.apache.catalina.logger.FileLogger"
    prefix="catalina_log." suffix=".txt"
    timestamp="true"/>
to the following:
    <Logger className="org.apache.catalina.logger.FileLogger"
    directory="logs" prefix="localhost_log." suffix=".txt"
    timestamp="true"/>

Then edit catalina.sh and remove all logging to

    "$CATALINA_BASE"/logs/catalina.out 2>&1
by entering:
    /dev/null 2>&1
For more information on Tomcat logging, see http://wiki.apache.org/tomcat/FAQ/Logging

Thanks to PSN for input!

Mixed-up pages after an upgrade

After an upgrade, you notice that pages are "mixed up" - that is, not all pages show the new version on their title bar. This may lead to many different errors and malfunctions.

This may be caused by two things:

This should fix all issues.

Figures do not match when running hourly versus daily reports

Imagine you run a report for Aug 25th, queue A, between 7 and 8 - it says there are 150 answered calls.
You run it again, between 7 and 13 and look at the hourly statistics - now it says there are 154 answered calls between 7 and 8.
What happened? that's simple - between 7 and 8, some calls were queued but not yet answered - so you are going to find them, but on the "Lost" page and with status "Ongoing".
You run the report again between 7 and 9, and now you see that the call was answered - because it was answered after 8 am.

If you run a report between 7 and 8, QM only sees data that cam between 7 and 8 - not what happened before of afterwards. It's like being at 8am and asking for future data. If you want to see what happened when you have a full day of data, run a report for a full day and look at the hourly breakdowns.

AMI connection not working in Asterisk 1.6

In order to perform a set of actions in Asterisk (eg. getting Live statistics, starting channel monitoring, logging agents on and off, setting call statuses) QueueMetrics needs to connect to Asterisk over the AMI interface.

In Asterisk 1.6 (AMI 1.1), in order to set up its calls, you have to make sure that the account that QM uses has ORIGINATE privileges as well as WRITE.

Printing and mailing out a report automatically

It is possible to print a full report to PDF automatically and have it emailed periodically with no human intervention.
In order to run the following script, you need to install the following packages on your server:(you need to enable the DAG repository to have nail).

The script is as follows:

This can be run automatically. For valid queue and time period parameters, see the chapter "Automating statistics download: the ROBOT profile" in the QM user manual.

In order to run the script, make sure that the ROBOT user is enabled in your QueueMetrics installation (it is disabled by default).

Installing QueueMetrics on a Debian or Ubuntu server

While on RedHat-derived systems a fully automated install using yum is available, on Debian the installation must be performed manually when running as root.

First, we make available the repository for Java:

Add the following lines:Now let's install Java:Then set:When you run:It should answer:Now let's install Tomcat:We will now turn off Java Security (see this FAQ entry if you need to keep it turned on, but it's easier if you turn it off now).Change the line TOMCAT5_SECURITY=yes to no.

Now let's prepare the database:

Enter the root password, and now the following commands to create a database:Now let's download and install QueueMetrics:Let's import the sample database: Now we download and install the MySQL connector:Start Tomcat and set your browser to http://myserver:8080/queuemetrics to access QM.

Help! The Real-time page is showing no data!

If the Real-time page will show no data at all - no agents logged on, no calls being processe, you should check the following items:See also:

Exception: java.nio.BufferOverflowException - Encoding problems when reading files

If QueueMetrics crashes with an exception like:this means that it is trying to read a file using the current Locale that is set for your server but this is not correct for QueueMetrics. You can check what is the encoding of the file names in your local server by typing "locale".

You can anyway force it to UTF-8 by changing JAVA_OPTS in the file /etc/init.d/queuemetrics:

Or, if it still does not work:Make sure that you kill the current Java process and restart it before logging on again in QM.

This error might also be triggered when reading a directory that has too many files, e.g. the place where you store audio recordings. You can override this behaviour by using the LocalFilesByDay storage model - it will also be way faster when retrieving recordings. See e.g.: http://astrecipes.net/index.php?n=387 and http://astrecipes.net/index.php?n=388

Help! QueueMetrics reports shows no data at all!

If you have activity in Asterisk but your QueueMetrics reports show no data at all - no calls processed, no agent sessions, you should check the following possible causes:

How do I modify or turn off the sounds on the Real-time page?

The default Real-time page that ships with QueueMetrics will play sounds when yellow or red alarms are triggered. The sounds played, or whether to play any, are controlled by a couple of system properties in the configuration.properties file:If you want to turn them off completely, just set them to blank.

Of course, alarm thresholds are user configurable from the Queue editor page.

Why do I see duplicate calls in the reports with a Caller-ID set to '*'?

If you see all (or many) calls in the Processed Calls or the Lost Calls reports as being present twice with the same start hour, the first time having a correct Caller-ID and the second time displaying '*' in the Caller-ID field, this means that you have duplicate data in your database.

This is usually caused by having mutiple instances of the qloaderd running at the same time - maybe you run them manually, or one instance was not stopped correctly during a restart. Stop them all manually and restart just one.

In order to "clean up" the database, use the queuePartialUpdater tool that ships with the qloaderd - it will basically unload a queue_log file and will reload it.

How do I secure access from a given subnet only?

Very often, you will want to make sure that the QueueMetrics application is accessible only from a given subnet. Even if QueueMetrics has its own security mechanism built-in, denying access to all clients that have no right to access QM will surely improve security.

In order to do so, you just edit the file: /usr/local/queuemetrics/tomcat/conf/Catalina/localhost/queuemetrics.xml so that it looks like the following one.

You could use the following format for the address instead of 127.0.0.1:If all goes well, when you restart QueueMetrics and try to access it from a forbidden IP address, you get the message "Access to the specified resource has been forbidden."

Please note that the queuemetrics.xml file is rebuilt upon automatic update, so you will have to edit it after running "yum update".

How to upload an older queue_log file

Imagine you have a queue_log file that uploads to partition P003, and is missing from timestamp 100 to 150; and imagine that old data is available in a file called queue_log.old
  1. Make sure there is no data in the table for partition P003 between timestamps 100 and 150.
    e.g SELECT * FROM queue_log WHERE partition='P003' AND time_id BETWEEN 100 and 150
  2. Stop importing on partition P003
  3. Move queue_log data newer than timestamp 150 to a new partition (eg P003B)
    e.g. UPDATE queue_log SET partition = 'P003B' WHERE partition='P003' AND time_id > 150
  4. Run the qloaderd on your queue_log.old file, so that it will load all data.
    You will have to watch its log file to se when it ends adding lines.
  5. Check that all data has been loaded
    e.g. SELECT count(*) FROM queue_log WHERE partition='P003' AND time_id BETWEEN 100 and 150
  6. Stop the qloader process
  7. Move back newer data from P003B to P003
    e.g UPDATE queue_log SET partition='P003' WHERE partition='P003B'
  8. Point qloaderd to your normal queue_log file, and restart normal importing
After you are done, try running a report to see if old data is actually seen by QueueMetrics.

Tracking timing and time-zone problems in QueueMetrics

It sometimes happens that a new QueueMetrics install has time-zone problems on a specified box. Generally speaking, the local time for the QueueMetrics instance should be the same as your own local time, and so should be for the MySQL server and the Asterisk server it relies on.

Small timing discrepancies can cause many problems, like calls not shown, wrong call duration and wait times on the realtime page, or even calls not showing at all on the realtime page.

Generally speaking, the first thing you should do if you suspect a timing problem is run a command that will sync the system clock with an high-precision atomic clock on all involved machines, for example:

As harware clocks tend to "drift" in the long period, it is a good idea to add this command to a nightly cron job that will keep the clocks of all involved systems below a one-second difference.

If you want to see the current clock and time zone for the QueueMetrics server and its MySQL instance, just click on the Licence page and those values will be shown. It's important that there is no difference between those values.

If one of the clocks is very different from the current time, it is usually a time zone problem on your box. This can usually be solved/detected running the following commands:

If everything seems correct and still the QueueMetrics server will insist on using the wrong time zone, you should try the following options:See also: http://minaret.biz/tips/timezone.html.

Transfers from the queue are not reported in QM

If your agents on a queue use to transfer calls out to other callers or to other queues, you may notice that this is not reported correctly by QueueMetrics. You may also notice that if you use agent channels, an agent stays idle after the transfer until the transferred call is over.

Unfortunately this is "by design"; this is because when you use the Attended transfer button on the agent's phone, the main PBX is not notified that the call is "handed-over", so it still thinks it's connected to the original agent. The official documentation says that "transfers performed by SIP UA's by way of a reinvite may not always be caught by Asterisk [...] The only way to be 100% sure that you will get this event when a transfer is performed by a queue member is to use the built-in transfer functionality of Asterisk".

So the only way there is to handle this case is then to use so-called "Unattended transfer", that is, setting the t option in the queue and then having your agent press # to start a transfer to a different extension. Unfortunately, this does not give you Attended transfer, that is, speaking to the receiver before handing over the call.

Our real-life workaround is to use the "#" unattended transfers of Asterisk to transfer calls only after having opened up a parallel conversation to negotiate with the receiver. We know it's sub-optimal, but this has been shown to work.

Using multi-stint mode in reports

When QueueMetrics run an activity report, its basic "unit of measurement" is the queue; that is the activity that your call made on a specific queue. This may lead to a situation that is harder to understand if you have spill-over queues in place, that is, if a call is not handled in one queue it is moved to a different one.

In order to address this problem, queueMetrics implements a multi-stint analysis mode, where mutiple passages on different queues are "joined together", like in the following example. Imagine this call:

With single stint mode you would see:With multi-stint mode you would see:and by clicking on the call detail, you get the whole history.

In order to have multi-stint work correctly, you should include ALL the queues that the call was handled upon in the same report - otherwise it will not find out where the call passed.

Of course, in real-life you can run both multi-stint and single-stint analyses when querying the performance of your call-center; you use multi-stint to see the performance from the point of view of the caller, and single-stint to see what happended from the point of view of the providers, e.g. service groups.

Missing records on KeyPress

Sometimes calls in Qm seem to go on forever... even if they have been terminated. This is often the case when your users exit the key by pressing a numeric key; some versions of Asterisk don't log this event correctly, so the call appears to be going on and on.

In order to check if this is the case, you should monitor your queue_log file when you exit a call by pressing a key; you should expect a line that looks like:

If such a line is not present, you may detect the event via the ${QUEUESTATUS} variable when the queue() app terminates, and produce a record like the following one:Where "myqueue" is the queue name and "key" is the key pressed (if you need to track it, otherwise set it to 1).

See also Handling ghost calls.

XML-RPC not working: Could not instantiate XMLReader parser

If the XML-RPC interface of QueueMetrics is not working, i.e you get no meaningful response, you have to look up on the catalina.out file in order to detect possible problems.

Xerces not installed

With Java 1.5 and Tomcat 5.5, you may encounter the problem as an error string stating redstone.xmlrpc.XmlRpcException: Could not instantiate XMLReader parser. This means the Xerces XML parser cannot be found.

If this happens, download Xerces from http://xerces.apache.org/xerces-j/ and put the file called xercesImpl.jar in your queuemetrics/WEB-INF/lib. This should solve your problems.

How to let Agents access the Realtime page

It is possible to let your QueueMetrics agents access the full RealTime page and not just the Agent's page:
  1. Create a new class for agents. You may call it RTAGENTS (Realtime Agents)
  2. Give your agents the following keys: USER AGENT CHPASSWD REALTIME. For the exact meaning of each key, see Appendix II of the User Manual.
  3. Create (or select) some agents and assign them to class RTAGENTS.
Those users will be able to login, access the realtime page, access the agent's page and change password.
If you want your agents to be able to see only a subset of all possible queues through the Realtime page, you should see also:How do I make some queues visible by some users only?.

Please consider that running the realtime page instead of the Agent's page is extremely expensive, computationally speaking, so run a few test before deploying this in a 1000-agent setting.

Handling 'Ghost Calls'

Sometimes calls in Qm seem to go on forever... even if they have been terminated. This may be caused by two reasons:
  1. In some versions of Asterisk, some ways of exiting a queue trace no log
    Mostly on older (1.0 and 1.2) versions of Asterisk, sometimes you discover that exiting a queue in a certain manner (eg a timeout, a transfer) consistently provides no end-of-call log. This makes it impossible for QM to know that the call is over.
  2. Asterisk sometimes randomly "forgets" to trace some end of call.
    This is a problem that happens on most large systems. If this is below 1% of all calls, it should be considered normal. Some installations are almost completely unaffected while others are heavily affected.
While case #1 can be fixed adding some dialplan logic to test the exit status and output a call closure log, case #2 still lingers.

QM handles this problem in two ways:

See also Missing records on KeyPress.

How do I run QueueMetrics with Java Security?

Java Security is a way to fine-tune the grants that a web-application has. This can be quite complex if you do not exactly know what a webapp is doing internally. You can set this by updating a policy file and running Tomcat in secure mode.
To make sure you are running under Java Security, you can check the value of the property java.security.policy under the Licence page - if it is set to something like =/usr/local/queuemetrics/tomcat/conf/catalina.policy, then security is enabled.

The following permissions apply to QM 1.4.5 - just add them to your catalina.policy file:

Of course you have edit them to:

Configuring ViciDial for QueueMetrics

ViciDial, a widely-used outbound dialer and campaign manager, can be configured to write its call activity logs directly to the QueueMetrics call database.

In ViciDial, this can be enabled as follows (Go to "System Settings"):

This should be it. Now create the campaigns in QM and make sure you're using the chosen LogID as the partition (e.g. if your log-id is VIC, you should enter sql:VIC as the file name).

Backing-up a QueueMetrics system

To make a backup of a working QueueMetrics system, you should backup the following items:Nothing else is needed.

See also:

How do I make some queues visible by some users only?

In order to make sure that some users (e.g. supervisors) can only see their queues, you should use QM's security model. When you protect something with a key, this means that you protect it (physically speaking) with a lock that opens if the user holds that key in his keyring. You know that eash user has a keyring, that is the sum of the keys that belong to his current class plus the keys that he individually has.

So, if you have a number of supervisors and a number of queues, you could protect each queue individually with a different key, and then give each supervisor individually the required key.

For example, you can do this:

When they log on, Alice sees queue A, queue C and queue D. Bob instead will see queue B, queue C and queue E.

Please note that if you have an aggregate queue, only the key protecting the aggregate queue will be ckecked, i.e. the checks on the members will NOT be performed (so you can have an aggregate queue that behaves differently in security terms from the set of its members, if you need it).

How is the field "N.Agents" computed?

The first cell of the top realtime panel ("N Agents") is computed as follows:Therefore it is very well possible that the first number does not match the following ones, because on one side an agent can be a known member of more than one queue, and on the other side an agent may not be a known member on any queue (in this case, it will be counted on the grand total but not on a queue-per-queue basis).

Using a different Asterisk manager port

It is possible to switch the port QueueMetrics uses to connect to the Asterisk manager interface fom the default port 5038 to any other port - use something like:This will set the Manager to port 1234 on server 10.10.3.27.

Error: "You do not have the rights to perform the requested action."

While working on the "Agent's page" and trying to log-on, log-off or pause an agent, the following error is displayed in the pop-up window after entering the Agent's code and Extension: "You do not have the rights to perform the requested action."

This means that QM is trying to connect to Asterisk to run that action, but Asterisk refuses the connection. In order to make it work, the following steps should be hand-checked:

  1. Are the connect credentials correct?
    The credentials supplied in the configuration.properties file should look like:
      callfile.dir=tcp:dial:bingo@1.2.3.4
    Check that they match the ones in Asterisk's own /etc/asterisk/manager.conf

  2. Is the dialplan context [queuemetrics] included?
    You can check that by typing the following command in Asterisk:
      asterisk*CLI> show dialplan queuemetrics

      [ Context 'queuemetrics' created by 'pbx_config' ]

        '10' =>           1. Answer()                                   [pbx_config]                    2. Wait(10)                                   [pbx_config]
      ..and a lot more stuff here....

    If it's not included, you can find the example file extensions_queuemetrics.conf under QueueMetrics' own README directory - just copy that to /etc/asterisk and #include it in the main dialplan (note: you should review that file before inclusion as it should be customized to fit your environment).

  3. Are you seeing connection attempts?
    If you open the Asterisk CLI, you should see a message when QM connects and disconnects. If you see nothing, there is some setup error (e.g. a firewall) that prevents QM to connect to Asterisk.

Using fully dynamic members with QM 1.4 and Asterisk 1.2

If you run QueueMetrics 1.4.1 or newer, you can fully use the new ADDMEMBER / REMOVEMEMBER to track agents logging on on a queue-by-queue basis. Unfortunately, Asterisk 1.2 does not automatically log them, so we must resort to something like the following example.

In this example, we assume that:

This is the relevant piece of dial plan:Do not forget to also change the value:in QueueMetrics' WEB-INF/configuration.properties file.

Using fully dynamic members with QM 1.4 and Asterisk 1.4

If you run QueueMetrics 1.4.1 or newer, you can fully use the new ADDMEMBER / REMOVEMEMBER to track agents logging on on a queue-by-queue basis. If you run Asterisk 1.4, most of the logging is already done correctly by Asterisk itself.

In this example, we assume that:

This is the relevant piece of dial plan:Do not forget to also change the value:in QueueMetrics' WEB-INF/configuration.properties file.

Tracking agent extensions for outbound dialing

When you do outbound calling, it's easy to track the extension that is doing outbound calling. It would be nice to match the agent that is logged on to that extension.
To do this, we must store the current agent's estension in a global variable:When you need to dial out you do:This way it works easily.

How to use subqueues

If you work in an environment where a single queue is used to service a number of different calling clients, it might be of interest to you to enable subqueues; i.e. to have the queue name rewritten appending a client code at the end, so that you can query them from QueueMetrics as if each client was serviced by a dedicated queue.
You can also use this technique in order to have very few actual queues in your call center but you still want to differentiate callers based on their incoming DID, or the group they belong to.

To set up this feature you should:

  1. Be running qloaderd and being successful in using the MySQL storage in QueueMetrics
  2. Create the new table qlog_opencalls as described in the qloaderd documentation
  3. Enable subqueues changing the qloader.pl file and setting:
      my $use_subqueue = 1;
  4. when you call a queue, you pass the DID code in its URL parameter, e.g.
      exten => s,8,Queue(queue-service|t|1234||180)
  5. When qloaderd picks up the call, it will import it as queuename.code; in the example above, it would import the call as queue-service.1234.
Please note that you should mantain the qlog_opencalls table yourselves, deleting periodically rows with a 'lastUpd' timestamp over one day old and optimizing it as needed.

How to write internationalized data to the database

If you use an internationalized version of QueueMetrics for a language based on a non-Latin character set, you may find yourself unable to write strings in your own language (e.g. the name of a queue) into QueueMetrics. This is usually not caused by QueueMetrics itself (that is completely UTF-8 compliant) but by the underlying MySQL instance.

In order to make sure that your charset is accepted by your database:

  1. Make sure that MySQL is installed in/for your language.
  2. Run the following commands on all tables of the database but the queue_log table:
      ALTER TABLE `call_status` CHARACTER SET utf8;
      ALTER TABLE `pause_codes` CHARACTER SET utf8;
      ....
    This tells the database engine to accept UTF-8 on all storage tables.
  3. Modify the connection string in web.xml so that it ends with:
      ....&useUnicode=true&characterEncoding=utf8&characterSetResults=utf8
    This tells the MySQL connector to force UTF-8 encoding when talking to the datbase server.
In our experience this is usually all that is needed to run an Unicode datbase instance.

Error: OutOfMemory: Unable to create new native thread

After running QueueMetrics for a while, the JVM stops with the exception "OutOfMemoryError: unable to create new native thread". This is usually caused by using the wrong JVM / Tomcat / Linux Kernel set, and is usually solved by:QM will run just fine with any JDK >= 1.4.2 and Tomcat >= 4.0, so there is usually no great benefit in running the very latest version of them.

See also: Java thread tuning.

Metadata file does not match checksum in Yum

When trying to install or update via Yum, you get an error like:This might be caused by having corrupted metadata information, and it sometimes cannot be fixed even if you runyum clean all. If this is your case, try the following:And will then run the yum update queuemetrics command.

Some pages won't compile and show JasperException

It sometimes happens that some pages of QueueMetrics cannot be opened; they crash during the JSP compilation stage with a "JasperException" showing that the page cannot be compiled.

This is often caused by having the wrong system-wide charset encoding, so that the source files cannot be read correctly from the disk.

To check if this is your case, you should go to the Licence Page, click on the [...] link to see all Java properties and check the value of file.encoding that should be ISO-8859-1. If it's anything else, it is a good idea to tell the Java subsystem to use this as a default encoding. To do this, you have to set an environment variable before starting Tomcat:

This tells Java to start by using ISO-8859-1 as the default file encoding and use a minimum of 256 megabytes and expand the memory pool as needed up to 512 megabytes. You should also set this in the /etc/init.d/queuemetrics startup file, so that it's set system-wide when QueueMetrics starts.

See also FAQ: Out of memory error for more information on Java setup variables.

Tracking hourly call distribution for multiple incoming DIDs

If you have multiple incoming DIDs pointing to the same queue, and you would like to track the hourly distribution of calls on each DID for planning, there is a simple thing you can do. You create a "virtual queue" for each DID, then when a call comes in into that DID, and before passing it to the actual queue that's servicing it, you write two log lines as if it was a lost call. Then you can define each "virtual queue" in QueueMetrics and run reports on it like you currently do; you will find all calls as "lost" but you do get call count, incoming caller id and hourly/daily/weekly call distribution.

In practice what you do is modify the dialplan so that:

exten => s,n, .....
exten => s,n,Macro(qm-lostcall,did-11,${CALLERID(name)})
exten => s,n,Queue(service-q,,30)
exten => s,n, .....

[macro-qm-lostcall]
; ${ARG1} - the name for the fake queue
; ${ARG2} - the caller id to be logged
exten => s,1,System( echo "${EPOCH}|${UNIQUEID}.1|${ARG1}|NONE|ENTERQUEUE||${ARG2}" >> /var/log/asterisk/queue_log )
exten => s,2,System( echo "${EPOCH}|${UNIQUEID}.1|${ARG1}|NONE|ABANDON|0|0|0" >> /var/log/asterisk/queue_log )

Now if you want to know what happended through the usual statistics, you run a report for queue service-q, while if you want to know about the incoming DID #11 you run a report for did-11.

See also Tracking the incoming DID on a queue.

Why do some calls disappear from the Realtime page?

You know that most call centers have a 80/20 rule (80% of the calls taken withing 20 seconds), so it is very abnormal for them to have calls answered after tens of minutes. In order to avoid showing calls that are actually logging anomalies, QueueMetrics considers calls that have been waiting too long or have conversation times too long on the realtime page as errors and does not show them anymore.

The basic wait duration is 1000 seconds, but if your call center shows such calls routinely, you can change this feature or turn it off altogether through the following configuration.properties settings:

Why does the Agent report show all Agent levels as "Undefined"?

The reason is usually pretty simple - because they are undefined. Whenever QueueMetrics runs a report on a queue, it loads the "agent level" information from that very queue definition that is being run - this means that if you use the same queue multiple times, e.g. once by itself, once as a member of an aggregate queue, you'll have to set the agent priority for all cases.

In order to assign agents to a queue, you follow the following procedure:

Of course, in order for this to produce meaningful results, you should set up penalities accordingly in the queue definition for Asterisk.

Page encoding problems (Getting "JasperException: Exception parsing file" or "JasperException Error: Cannot read file" errors)

Some JVM's, particularly IBM's, seem to be a bit more picky on page encoding that Sun's. The result is that some pages of QueueMetrics do not get compiled at all, resulting in one of the exceptions above.

If this happens to you, please notify Loway of the pages you are having problems with, so that we can fix them for the next version. There is also a simple workaround that will make the page readable in most cases:

Tracking the incoming DID on a queue

If you have a scenario where you have multiple incoming DIDs pointing to the same queue, and want to track how many calls you received on the queue from each of those DIDs, the easiest thing to do is use the Area Analysis function of QueueMetrics to take care of this automatically.

When a call comes in, you add the DID code to the incoming Caller ID, so that you get incoming numbers like "D7-0123456" where D7 means the call was received on DID 7 and 0123456 is the original Caller-ID. Then if you go to the Area Analysis in QueueMetrics, you can ask for a call report based on a number of Caller-ID digits (like 2 in this case, to extract the first two characters of the caller), and it will break down all calls by DID code.

You may also use this same function to track other information associated with the same calls, like multiple IVR choices pointing to the same queue.

For more information on Caller-ID rewriting, see the FAQ entry "How to set the Caller-ID".

If you need a break down of calls by calling DID and time, see Tracking hourly call distribution for multiple incoming DIDs.

Deploying QueueMetrics with JBoss

It is possible to deploy QueueMetrics into a JBoss application server:

How to set the Caller-ID

If you need to rewrite the caller-ID of the incoming call and want the rewritten number to apperar in QueueMetrics, you should set the following Asterisk dialplan variable: CALLERID(num). This variable gets written to the queue_log, so that the information can be picked up by QueueMetrics.

The popular TrixBox distro sets the authenticated caller-ID name in the CALLERID(name) variable but not in CALLERID(num); the following piece of diaplan will do the trick:

[from-trunk-custom]
exten => _X.,1,Set(CALLERID(num)=${CALLERID(name)})
exten => _X.,n,Set(CALLERID(name)=${CALLERID(name)})
exten => _X.,n,Goto(from-trunk,${EXTEN},1)

(thanks to Barry for pointing this out).

The Qloaderd process will stop working at night

The Qloaderd process will send data from a machine's queue_log to a MySQL server. It was designed for maximum safety, so that in case there are connection errors it will try resubmitting the same query over and over, but we noticed that with some versions of the DBI it will not be able to reconnect successfully if the MySQl connection was terminated because of inactivity.

In order to avoid this, you may want to set the inactivity timeout to a very high value, by editing or adding the following variables in the [server] section of your /etc/my.ini file:

interactive_timeout = 2764800
wait_timeout = 2764800

This will avoid MySQL marking the connection as dead when the CC is inactive for may hours.
Starting from version 1.3, Qloaderd will also issue periodical queries every 15 minutes even when there is no activity to avoid this problem.

How to fix timing problems in the realtime page when using MySQL storage

If you run QueueMetrics with MySQL storage mode, you will likely have QueueMetrics reside on a server that will be different from the one Asterisk is, and might as well be different from the one MySQL is.

If the clocks of all or some of those those machines have small discrepancies, this can lead to minor problems with the realtime page, showing calls with negative or positive length offsets and sometimes completely ignoring the shortest of calls.

Those problems will be experienced only with the realtime page, while the standard reports are unaffected (as they compute durations from actual data and not by inferring them from the local time).

To fix those problems, we strongly suggest you use a high-precision time syncing utility like the NTP package found in most Linux distros, and that you run it on all servers involved (Asterisk, QueueMetrics and MySQL) in order to have highly coherent timing and logging data.

To do this, simply run the following command as root to fix your system clock:

ntpdate ntp.ien.it

We strongly suggest running it daily using a cron job so that you make sure the servers are consistently time-aligned in the future.

How to monitor multiple queues at once

To monitor multiple queues at just create a composite queue, that is a queue which definition is a set of other queues; they can be inbound, outbound or mixed. To do this, log on as an administration, click on "Edit queues", then fill in the form on the bottom of the page called "Add new queue".

Fill-in the following form fields:

Save and go back to the home page. Now you are ready to test your composite queue on both historical and real-time reports.

In thisway you can run a report for a composite queue and see the details of a number of queues at once (this is very useful e.g. for real-time monitoring).

We also suggest creating a queue named "00 All" that will always appear as the first in the drop-down queue selection box and will allow easy access to the overall monitoring.

How to change the realtime page refresh time

You can modify the realtime page refresh rate from the basic 20-second period to any value you choose. Just set the following property:

#In how many seconds is the realtime page to refresh?
realtime.refresh_time=18

We do not suggest using a value less than 10 seconds, or the browser will flicker a bit. Time ranges in the 15-30 seconds usually work best. Please consider that decrementing the refresh timeout will add more load on the server.

Logged-on agents disappear at midnight

If your agents work in shifts around midnight, with a plain QueueMetrics installation you will see that they will "disappear" at midnight from the Realtime screen, as if they logged off, though they will continue receiving calls (and calls they receive will be reported correctly). Calls handled over the midnight (i.e. started before the midnight and ending after the midnight) may seem to have been dropped as well from the realtime screen.

This is because QueueMetrics will consider agent logon information starting from the last midnight, and this arrangement works great for call centers working during the classical 9-to-5 office hours. If you need a different arrangement, you can use a "sliding window" model, where QM will look for information during a time period you define. For example, to set a sliding window of 12 hours, you would set the following property:

#The hour of the day to start real-time monitoring or sXX: sliding window of XX hours
realtime.startHour=s12

You could also set it to "s18" or "s24" to look back 18 or 24 hours respectively - of course, the longest this period, the more data QM has to process each time.

Non existent calls taken when no agents were available seem to be lagging in the queue

If you enable the maxlen, joinempty, leavewhenempty options in a queue, it is well possible that if a call enters a queue with too many waiters, or no available agents, the call is not queued but terminated immediately. Unfortunately such ghost calls seem to be present in QueueMetrics and never being taken by any agent. This is because Asterisk is not logging the piece of information that tells us that the call was rejected from the queue, so QueueMetrics has no way to know the call is not there anymore.

What we do to fix this case is that whenever the queue() command terminates and goes on with the dialplan, we make sure that we output the missing information - and this is in fact pretty easy..

We configure a queue like this:

[myqueue]
exten => s,1,Queue(queuename||)
exten => s,2,System( echo "${EPOCH}|${UNIQUEID}|queuename|NONE|EXITWITHTIMEOUT|1" >> /var/log/asterisk/queue_log )

Of course this is a very simplified case, but you should get the idea of how to do it.

Fully dynamic agents and QueueMetrics

 QueueMetrics requires a little tweaking to work with fully dynamic agents. This is because the AddQueueMember() command will not log data correctly to queue_log, so we have to do this manually.The best way to do this is to log on your agents to all the queues you need and do an AGENTLOGIN, and then log them off when you do an AGENTLOGOFF. Calls will be reported correctly to the correct queue anyway.

For example, if your operator works on queue q1 and q2 and q3, you would do like this:

; Add Member - 422
exten => _422XX,1,Answer
exten => _422XX,2,AddQueueMember(q1,SIP/${EXTEN:3})
exten => _422XX,3,AddQueueMember(q2,SIP/${EXTEN:3})
exten => _422XX,4,AddQueueMember(q3,SIP/${EXTEN:3})
exten => _422XX,5,System( echo "${EPOCH}|${UNIQUEID}|NONE|SIP/${EXTEN:3}|AGENTLOGIN|-" >> /var/log/asterisk/queue_log )
exten => _422XX,6,DBput(dynlogin/log_Agent-${EXTEN:3}=${EPOCH})
exten => _422XX,7,Hangup

; Remove Member - 423
exten => _423XX,1,Answer
exten => _423XX,2,RemoveQueueMember(q1,SIP/${EXTEN:3})
exten => _423XX,3,RemoveQueueMember(q2,SIP/${EXTEN:3})
exten => _423XX,4,RemoveQueueMember(q3,SIP/${EXTEN:3})
exten => _423XX,5,DBget(ORGEPOCH=dynlogin/log_Agent-${EXTEN:3})
exten => _423XX,6,Set(RV=$[${EPOCH} - ${ORGEPOCH}])
exten => _423XX,7,GotoIf($["${RV}" = "0"]?10:8)
exten => _423XX,8,System( echo "${EPOCH}|${UNIQUEID}|NONE|SIP/${EXTEN:3}|AGENTLOGOFF|-|${RV}" >> /var/log/asterisk/queue_log )
exten => _423XX,9,DBdel(dynlogin/log_Agent-${EXTEN:3})
exten => _423XX,10,Hangup

If you use Local/XX@ext channel rewriting to Agent/XX, make sure to log 'Agent/${EXTEN:3}' instead of 'SIP/${EXTEN:3}'

As a further alternative, you could have your agents login in the morning to a "fake" extension producing the log line, then join each single queue without producing a log line, and then logging off in the evening to another "fake" extension producing the log line.

As a last alternative, if you need to track the actual logon-logoff times for each queue, what you have to do is to log on each queue by logging to a different agent, like:

And so on. This way you can track precisely the queue logon and logoff times for each agent on each queue. In order for this to work, you must set the following configurtation properties:

default.rewriteLocalChannels=true
default.rewriteLocalWithQueue=true

The login-logoff code in this case is as follows (for queue 'q1'):

; Add Member - 422
exten => _422XX,1,Answer
exten => _422XX,2,AddQueueMember(q1,SIP/${EXTEN:3})
exten => _422XX,3,System( echo "${EPOCH}|${UNIQUEID}|NONE|Agent/q1-${EXTEN:3}|AGENTLOGIN|-" >> /var/log/asterisk/queue_log )
exten => _422XX,4,DBput(dynlogin/log_Agent-q1-${EXTEN:3}=${EPOCH})
exten => _422XX,5,Hangup

; Remove Member - 423
exten => _423XX,1,Answer
exten => _423XX,2,RemoveQueueMember(q1,SIP/${EXTEN:3})
exten => _423XX,3,DBget(ORGEPOCH=dynlogin/log_Agent-q1-${EXTEN:3})
exten => _423XX,4,Set(RV=$[${EPOCH} - ${ORGEPOCH}])
exten => _423XX,5,GotoIf($["${RV}" = "0"]?8:6)
exten => _423XX,6,System( echo "${EPOCH}|${UNIQUEID}|NONE|Agent/q1-${EXTEN:3}|AGENTLOGOFF|-|${RV}" >> /var/log/asterisk/queue_log )
exten => _423XX,7,DBdel(dynlogin/log_Agent-q1-${EXTEN:3})
exten => _423XX,8,Hangup

How to install and update QueueMetrics using yum

Yum is a package manager that is used on a number of Linux systems, notably Red Hat / CentOS and derivatives like Asterisk At Home / TrixBox, in order to ease the installation and update of software packages.

If your systems uses yum, you can install QueueMetrics from scratch using the following commands:

wget -P /etc/yum.repos.d http://yum.loway.it/loway.repo
yum install queuemetrics

And then following the on-screen instructions in order to create the database.The first line is needed in order to add Loway Research as one of the authorized repositories into which yum can search for packages.

To update QueueMetrics to the latest version, just use:

yum update queuemetrics

And then have a look at the Updating.txt file in order to modify the database and/or the configuration.properties file if so is needed.

As an alternative, you may want to delete it and reinstall it from scratch, as:

yum erase queuemetrics
yum install queuemetrics

Why do I get the error 'Bad interpreter' trying to run a shell file or an AGI?

If you run a command file that is written in Perl, and the file does not seem to run at all unless it is launched manually with "perl filename.pl" it is very likely that you forgot to convert it from DOS format to UNIX. You usually get the error "bad interpreter" when running it manually.

To solve this problem, type dos2unix commandname - the file will be changed from DOS format to UNIX and will be immediately runnable by typing ./commandname

If this is not enough, make sure that the file is executable (chmod a+x commandname) and that the path of the Perl interpreter as specified in the first line is correct for your environment.

What do the fields named UNK and BSY mean?

In the realtime view, there are two fields that may look puzzling: BSY and UNK.

Why doesn't my AGI file seem to work

When installing a new AGI script, sometimes Asterisk seems to reporting that the file gets executed with result 0 while the file it is not in fact being executed at all.
If it does not, there are a few possible reasons:
  1. the script does not exist at the given agi-bin location or it is not "visible" to the user running Asterisk (solution: update unix file permisions)
  2. the script is not executable - try running it manually (do a "chmod a+x queueDial.agi")
  3. the script is in DOS mode - i.e. uses CR/LF as the line endings - and won't start from the shell (do a "dos2unix queueDial.agi" to fix it)
  4. check if the file /var/log/asterisk/agi-log.txt is read/writeable by Asterisk

How to implement a dial-out queue

The following is is a piece of real-world dialplan one of our clients is using:

exten => _9XXX.,1,Set(MY_QUE=${EXTEN:1:3})
exten => _9XXX.,2,Set(MY_NUM=${EXTEN:4})
exten => _9XXX.,3,Set(MY_AGENT=${CALLERID(num)})
exten => _9XXX.,4,NoOp,Ag: ${MY_AGENT} N: ${MY_NUM} Q: ${MY_QUE}
exten => _9XXX.,5,MixMonitor(Q-${MY_QUE}-${UNIQUEID}.wav|b|)
exten => _9XXX.,6,DeadAGI(queueDial.agi|${MY_NUM}|Zap/g0/${MY_NUM}|q-${MY_QUE}|Agent/${MY_AGENT})
exten => _9XXX.,7,Congestion

This example needs a three digit campaign number, like '301'. If you have to dial the number 01234567 for campaign #301, you actually dial 9 301 01234567 so that the system knows on which outbound queue the call is being handled. The agent code is inferred from the current terminal it is being used and all calls are saved to disk for future reference with a name that QueueMetrics can understand (so you can listen to them with a click from the mouse).

As this feature requires making a number of changes to the Asterisk configuration, we suggest you proceed one step at a time during its implementation:

  1. First change the dialplan in order to have a NoOp() console output - like the example above steps 1-4 - so you can see that your changes to the dialplan are correct and do indeed work
  2. Then try adding the queueDial.agi in that point in the dialplan so that you are sure it is called through the diaplan (you can see it being called through the Asterisk command line interface, though it might not work yet)
  3. Once you are sure it is called, check if all file permissions are OK and the queueDial.agi does actually what it is supposed to do - places a call and adds lines to the queue_log. If it does not, chances are it is not being executed at all - see "Why doesn't my AGI file seem to work?"
  4. When everything is ready, configure QM to pick up the new queue you created.
Note: if you run some of the latest Asterisk 1.4s, it is possible that some of the calls terminated using the queueDial.agi script fail and remain "hung" in QueueMetrics - to fix this, see Quemeterics not recognising remote caller hangup on the forums.

Error: java.sql.SQLException: Invalid authorization specification message from server: 'Access denied for user: 'queuemetrics@localhost.localdomain' (Using password: YES)'

You always think that your machine is localhost when connecting from the same host, but MySQL sometimes thinks that it's localhost.localdomain and so your credentials will not match. On MySQL, try the following line:
grant all privileges on queuemetrics.* to 'queuemetrics'@'localhost.localdomain' identified by 'password';

Error: java.sql.SQLException: Cannot convert value '0000-00-00 00:00:00' from column 14 to TIMESTAMP

You are using a version of the MySQL connector that is >= 3.1. To solve this problem add the parameter zeroDateTimeBehavior=convertToNull to your JDBC connection string located in WEB-INF/web.xml, like in the following example:

Error: java.sql.SQLException: Data source rejected establishment of connection, message from server: 'Host 'localhost.localdomain' is not allowed to connect to this MySQL server'

You always think that your machine is localhost when connecting from the same host, but MySQL sometimes thinks that it's localhost.localdomain and so your credentials will not match. On MySQL, try the following line:
grant all privileges on queuemetrics.* to 'queuemetrics'@'localhost.localdomain' identified by 'password';

Error: java.lang.ClassNotFoundException: com.mysql.jdbc.Driver

The Java MySQL driver was not found. Try downloading it again, putting the appropriate JAR file in WEB-INF/lib and restarting the servlet container.

Error: "Il verbo '.....' non consente la creazione di una nuova sessione"

Your session timed out for inactivity; when you then click on a link, the system tells you that you have to log on again.

Error: java.sql.SQLException: Access denied for user 'queuemetrics'@'mydb' (using password: YES)

The error means that the user and/or password given in WEB-INF/web.xml do not match credentials supplied with MySQL. On MySQL, try the following line:
grant all privileges on queuemetrics.* to 'queuemetrics'@'mydb' identified by 'password';

Error: java.lang.NoSuchMethodError

This error manifests itself usually after upgrading the webapp and has no apparent meaning, as the required class seems to be present in the compiled jar files. It is usually due to one of the two following causes:To solve this problem:This should fix your problem. If you fear that you have too few RAM for QueueMetrics, an ongoing "deep" garbage collection can slow down the JAva VM to a crawl and prevent it from stopping when requested to do so. In this case,see also "Out of memory error".

QueueMetrics does not seem to work with GCJ

QueueMetrics does not currently work with GCJ 3 and seems to use a lot of CPU and memory on GCJ 4. GCJ is a free Java compiler/interpreter usually found on most Linux distributions but is not currently 100% compatible yet with the standard Java bundle - see http://gcc.gnu.org/java/.

You should use an industrial-strength Java SDK instead, like the ones from Sun or IBM. Our suggestion is to go for the latest Sun SDK available.

Java Security errors

On some systems, notably Debian, the Tomcat package is installed by default with Java security policies active; such policies are very restrictive and may block Tomcat when trying to access the database or read files from the local file system.

See the entry Running with Java security for an example ruleset that applies to QM 1.4.5.

If this is not possible, you'd better install Tomcat fresh from the tar file as described in the User Manual.
See also the Tomcat Security Manager HOW-TO for a better undertanding of the security manager.

Error: "Problema update DB: com.mysql.jdbc.MysqlDataTruncation ..."

To fix this problem, that comes with the newer versions of MySQL and Connector/J, add the parameter jdbcCompliantTruncation=false to your JDBC URI in WEB-INF/web.xml.

Error: "Il verbo '.....' richiede una chiave non disponibile all'utente corrente"

You need a key you do not currently have to run the required transaction. Likely, your session timed out for inactivity, so you have no key at all associated with your profile; when you then click on a link, the system tells you that you have to log on again.