Users and classes can be added, modified and deleted right from QM.

A list of users is presented and you can filter it by class or user name.

For each user, the login and full name are shown, together with the current class and any additional user keys. A user must be enabled in order to log on, so if you want to prevent somebody from logging on without deleting its user information, you can simply disable it. A number of default users are shipped with Enable: No in order to prevent unauthorized access.

The list of users is paged and you can use the top box named "Filter" in order to search for a specific user or a set of users that match the entered substring. You can also click on the column name to toggle ascending versus descending sort order.

The "Create new" button lets you add new users while the "Show classes" button leads to the class editor.

When you add or edit a user, you are presented with a list of fields to enter:

	Note
	When you first log on to QueueMetrics, you must change the passwords to all default users. Failure to do so represents an important security breach!

User classes can be configured freely; you can create individual key rings with special privileges to best suit your needs.

Each class has a set of keys that can be freely edited in much the same way as users by clicking on the "edit" icon (the pencil).

No class can be deleted as long as there is at least one user that is member of it.

The default classes should be enough to get most systems started:

A list of queues must be set before accessing QM. Each queue can be made visible to only a specific set of users by adding a key - this can be useful if, for example, each queue has a manager viewing data for it, while only a CC manager sees data for all queues in the center.

You can search for a specific queue by entering data into the Filter box on top of the page, or change the default sort order for the list by clicking on one of the column names.

The default page shows:

The pencil icon will let you edit the queue, while the "People with pencil" icon lets you change queue associations.

For each queue you have to define:

By clicking on the Agents icon, you can define the position of each agent as a member of the service groups for that key. An agent cannot be a member of more than one group per each queue s/he is a member of.

It is of course perfectly legal for an agent defined not to be used in a specific queue.

18.3.3. Configuring queues to be processed by the AGAW Runner

The AGAW Runner will use the following rules to decide which queues and agents to process:

• All queues that are "simple", i.e. not composite, are taken into consideration for processing by the runner. All queues that have the AGAW runner enabled will be actually processed (you must enable that manually in the queue config page).
• All agents that are linked to a queue are processed for that queue, even if there is no data for them; plus, any unknown agent that is detected working on a queue is processed for that queue..

In order for a queue to be processed by the runner, and show visible metrics to the user:

• The "Will AGAW be run…" must be set to "yes"
• The Items defined must be > 0 (or the agent will see no metrics)
• The AGAW enabled should be "Yes"
• The AGAW look back period can be left blank (default). This is the size of the look-back period the AGAW runner uses.

The set of metrics that is enabled and their alarms is defined in the AGAW queue configuration screen (click on the "AGAW alarms" button):

As you can see, for each metric there are a couple of switches that decide:

• Whether that metrics is to be shown at all
• Red and yellow alarm levels for the whole queue (to be shown in AGAW, so they might differ from the ones used for the real-time page)
• Red and yellow alarm levels for each agent separately

These settings are applied from the next run of the AGAW runner, so they can be modified while the AGAW runner is active and will be picked up when the relevant queue is processed.

All values are always computed; you can toggle visibility of values on and off (if they are "Off" they are visible in the AGAW monitor but NOT to the user).

Alarms can be expressed as:

• Integers (for time periods and n. calls)
• Floating-point values ( e.g. > 3.7)
• Percentages (e.g. > 10%).

While percentages for the Queue part translate to the corresponding ratio (e.g. 10% means 0.1) in the Agent part they are anchored to the Queue metrics - that is if number of calls is at a given moment 1000 and there is an agent alarm at "< 1%" , if the number of calls taken by that agent are less than 1% of the queue the alarm will be triggered.

If you need to express a fixed percentage in the Agent part, use the corresponding ratio, as in the Qualified Conversion example above.

Agents can be configured so that:

When editing an agent, the following screenshot appears:

For each agent in use, enter:

If you want an agent to log on to their own page, you also have to create a user with the same name.

On the bottom of the page, the current association of that agent to a set of queues is shown.

The following configuration transaction lets you define locations for your agents. To access this page, a user must be holding the USR_LOCATION key.

Each location has a short name, a longer description, and a visibility key, so that only users holding that key may select that location as a source for reports.

A location cannot be deleted if at least one agent is defined for that location.

We define a call outcome as a flag to be added to a call, either when the call is ongoing or when the call has just finished, that will signal the result of the call from a business point of view. Such a flag is optional for QueueMetrics and can be added to both incoming and outgoing traffic.

The call outcome will be defined by a numeric sequence that the agent will either key in on their telephone terminal or report through QueueMetrics itself through the Agent’s page. QueueMetrics will not consider how the sequence is entered, as long as it’s present in the queue_log data it runs on. Such records can be generated, for example, by an outbound dialler that is able to pre-screen answered traffic.

To minimize internal searching costs, the call activity must be entered either while the call is in progress or within one hour of its completion. If more than one call activity code is entered, the latest takes precedence over the previous ones.

As you can see, each outcome can set two flags: a "This call qualifies as contact?", "The call qualifies as Qualified Contact" and a "This call qualifies as sale?" flag. This will be used in order to produce statistics on traffic (see section Section 4.12.1, “How are Call Outcomes calculated?”).

If a call code is found but not defined through the configuration screen, QM will report on it and treat it as a "No contact" and "No sale" call.

The editor page lets you set:

The agent’s time is defined in QueueMetrics as made up of different activities. The main activity for an agent will be "Available time", i.e. the time when an agent is ready taking or placing calls. When an agent pauses out of "Available time", they may want to flag the reason for the pausing, e.g. doing backend activities, lunch, etc. This way you can track agent activities punctually. If they don’t flag a pause, it will be computed as simply "Pause" time.

Each pause code is written on the queue log while the pause in progress, i.e. after the agent goes on pause and before the agent stops that pause. The pause code will usually be defined by a numeric sequence that the agent will either key in on their telephone terminal or report through QueueMetrics itself through the Agent’s page. QueueMetrics will not consider how the sequence is entered, as long as it’s present in the queue_log data it runs on.

For each pause code, it is possible to tell QueueMetrics whether that time is billable (from a business perspective, e.g. time an agent is disconnected from the ACD but doing back-office activities) versus non-billable activities (e.g. pausing for lunch, taking mandatory breaks, and so on).

All activities are optional and may be added or deleted at will. The following fields apply:

The set of current QA forms can be configured through the QA form editor. It shows the current set of defined forms and lets you performs the usual operations (search, filter, sorting, paged listing…).

The names of each section and the number of items that have been input for that form are shown on the front page. If a form ahs any number of items input, it is considered "locked" and cannot be modified anymore, though you can create a different form with the same set of items.

The form editor looks like the following page:

You can enter:

To edit the set of items that belong to a form, you should have no data reported for that form. If you have no data, the item editor icon will show from the main form page.

The editor will look like the following page:

To add a new element, just select an element on the top form and a section it should be added to.

On the bottom of the page, you can edit the elements by changing them, moving them up or down and removing them.

18.8.1. Configuring QA items

The set of items that are selectable as members of a form can be configured by the user by clicking on the "Edit items" button at the bottom of the QA forms editor.

New items can be added and the description can be edited if needed. The shortcut items are marked with a red icon. Mandatory fields are marked with a green icon. Shortcut items are items that will force to zero the overall form score if they receive a score below the "Issue" category.

The Engagement code cannot be modified once input, and there can be no two items with the same engagement code.

Items cannot be deleted if they are in use by at least one form. You can see the set of forms that are using the chosen it at the bottom of the editor’s page.

Since version 1.6, QueueMetrics allows for the configuration of reports. This makes it easy to tailor specific reports to specific users, instead of having all reports shown to all users. It also adds the fexibility to hide part of a report to users that do not have specific keys, and to edit the titles and subtitles for each reports.

In order to understand reports, it must be understood that a QueueMetrics report is made of a number of screens (the "pages" that the report is made of), each of which is in turn made of items (the actual tables containing data).

All elements (reports, screens and items) can be key-protected - so it is easy to make a full report, or just a part of it, visible to some users only.

As both screens and items have a display order you may want to control, they all have an numeric attribute called Sort Order that orders elements from the lower to the highest.

As QueueMetrics reports include an "All reports" page that in turn includes all elements in order, it is possible to control which elements are visible in it at the screen and item level; this is useful because you usually do not want extremely large items (like call lists, that may span over thousand lines) to appear in it.

One last word must be spent for titles; as QueueMetrics is an inherently multi-language application, titles may or may not be localized using QueueMetrics facilities.

18.9.1. Editing reports

In order to access the reports editor, from the homepage click on QueueMetrics settings → Edit reports.

There will usually be ony one report called "All reports" - this is an automatically-generated report that includes all available reports.

For each report, the number of associated screens is displayed.

Each report can be modified by clicking on the edit icon (the one that looks like a pencil) or the associated screens can be shown by clicking on the report title.

	Tip
	As creating a full report takes a while, it is possible to create multiple copies of the "All reports" items and then doing minor customizations by entering a new report name in the "Automatic report configuration" dialog. This is also handy when you upgrade QueueMetrics and want to test-drive new reports that were not previously available.

If you click on the edit icon, you will see the current report configuration:

• The title and subtitle can be chosen freely and will be shown to the users
• The type must be set to QM Report
• You can enter a visibility key to make this report accessible to some users only

18.9.2. Editing screens

A report is made of a number of screens. They are the multiple selectable pages that are available when you run a report. As the space is limited, each screen has a Short title as well as a full title.

You can see that the items are sorted accoring to their Sort index, just as they will be displayed in the main reports. You can also see the number of asscoiated items for each screen and whether the screen will appear in the "All reports" page.

Each screen can be modified by clicking on the edit icon (the one that looks like a pencil) or the associated items can be shown by clicking on the screen title.

If you click on the edit icon, you see the details, as shown here:

• The Short name is the one displayed in the horizontal page menu, so it should be very short
• The Title is the one displayed at the top of the page
• The Visibility key lets you hide this screen and all its associated items from user sthat do not have the specified key
• The Sort order is an integer value that tells QueueMetrics how to position this element in respect to all other screens.
• The Visible in All reports toggle decides whether this screen and its associated elements are visible on the "All reports" page

	Note
	Both the Short name and Title fields display a decoded, localized version of the string just below their input box. This is what the end-user will actually see.

18.9.3. Editing items

When clicking on a screen title, you display the list of items that belong to that screen.

You can see the title for each item, the Data Object tht actually creates data and its parameters.

Each item can be modified by clicking on the edit icon (the one that looks like a pencil).

• The Title field is the one displayed in bold on top of the table
• The optional Subtitle can be added as an explanation of the meaning of the graph.
• The Visibility key lets you hide this item from users that do not hold the given key.
• The Data Object is the routine that creates the requested table and/or graph. A list of available Data Objects is available here Section 6, “Report Details”.
• The Parameters field (if present) will let you add additional parameters that control the behavior of the Data Object.
• The Sort order is an integer value that tells QueueMetrics how to position this element in respect to all other screens.
• The Visible in All reports toggle decides whether this item is visible on the "All reports" page

	Note
	The Title field displays a decoded, localized version of the string just below their input box. This is what the end-user will actually see.

	Caution
	You cannot have multiple copies of the same DataObject on the same page.

In order to save time and make sure that QM is always up-to-date with the underlying Asterisk configuration, it is possible to run a wizard that will load the following data straight from Asterisk configuration files:

It is also possible to automatically create users out of the defined agents, so that they can log-on to QueueMetrics with the very same password they use to log-on to Asterisk.

In order for the wizard to be run, the user must hold the grants to administer users, edit queues, edit agents, and must hold the CONFIG key too.

If the user holds the required keys, the label "Setup wizard" will be shown on the front page:

By clicking on it, the administrator will be lead to the first step of the wizard.

At the top of this page is a dropdown menu that defines where asterisk configuration could be found. Actually the wizard is able to read information from:

By selecting the "File" source, the three edit boxes will let the administrator able to specify the local paths for the agents.conf, queues.conf and the users.conf file.

By selecting "Queue Log File" as source, the associated edit box will let the administrator able to specify the local path for the queue_log file.

	Note
	The users.conf file is optional and could integrate the information stored in the agents.conf file. The agents.conf file, instead, is not required only if the users.conf is present.

	Note
	If you don’t have the users.conf or the agents.conf file, you can leave in the edit boxes their default values and the system will be able to skip it if not found.

For sources different than "File", or "Queue Log File", the wizard will use some configuration options to know how to reach the required information. More details can be found in Section 18.12, “Configuring system preferences” and in Appendix D, System preferences.

When you have selected the source you want to be read, click on Next button. You will be redirected on the validation page. This page will inform you if the provided sources were succesfully read or, in the worst case, it will show you a message reporting an explanation of the error found.

If the validation fails, clicking on Next button you’ll be forwarded back to the first step, otherwise, you’ll be redirected to the next step.

The wizard will scan the available agents and presents you a list of agents to be created or updated. By default, this wizard will try not to modify an agent or a queue that is already present in QM, that is the found data will be shown but unchecked. Check on the items to include/exclude them as needed.

If no agents will be selected, by clicking on Next button the wizard will skip the next step and will forward you directly to the queue selection step. If at least one agent was selected, instead, when you click on Next button you’ll be redirected to the window shown below.

If the corresponding QM users, for selected agents only, are not present, they are created automatically by this mask.

Please note that if the wizard is not able to read the password associated to a specific user (because the password is not specified in the configuration files or because the wizard is reading information from AMI or realtime, or the queue log file, where password for agents are not shown) it will use the following rules:

The queues will be created or updated as needed; existing queues will not usually be overwritten without explicit user permission.

	Note
	A queue will be automatically checked to be updated if at least one of its agent member was selected to be updated and/or added.

	Note
	When updating a queue, the spilloff and queue members lists will be generated looking at the penalties associated to the agents read from the sources. If an agent is already present in a member or spilloff list, but it was not selected to be updated, he will not removed and/or moved from any list.

If you click to the Next button you’ll be redirected to the page above reported. This page will display a summary of the QueueMetrics database updates that have been scheduled to be performed. Clicking on the Yes button, the scheduled actions will be run and you will be redirected to the last page where a table listing the related operations results will be presented. Clicking on No button, instead, you’ll be forwarded back to the first wizard step.

The QueueMetrics database is now updated with the information found in the selected sources. You can go back to the home page clicking on Next button.

QueueMetrics could be updated and configured by means of external http queries made in a known format. This is really interesting for setting up a cron job to be completed sometimes during the day. When QueueMetrics receives external http queries, it will perform all the configuration wizard steps together (see Section 18.10, “QueueMetrics configuration wizard”) assuming default answers. This will result in a background synchronization between your asterisk boxes and the QueueMetrics database. To be able to run periodic QueueMetrics update, you need:

The URL to be used to start the unattended configuration system has to be formatted as follow:

http://qmaddress/queuemetrics/autoconf_Robot.do?user=demoadmin&pass=demo \
 &stype=0&agents=/etc/agenti.conf&queues=/etc/code.conf&users=/etc/users.conf

The meaning of specified parameters is below reported:

The user, pass and stype are mandatory; the other parameters are optional and have no meaning when the requested source is different from "file".

The other parameters are:

When QueueMetrics terminates the procedure, it will answer with a result page where the term "SUCCESS", or "FAIL", will be present reflecting the operation success status. In this page will be also present a list of the performed operation (and their result status). An example page is reported below:

System preferences can be edited by editing a text file called configuration.properties located in the WEB-INF directory of the QM webapp. The absolute path on your system can be found by looking at the System path property on the Licence page.

A complete list of preferences can be found in the chapter Appendix D, System preferences. Once a preferences value is changed, it is enough for the user to log off and log on again; restarting the servlet container is not needed.

Once your copy of QueueMetrics is correctly installed, the Queue Runner can be run using a script that is available as WEB-INF/mysql-utils/agaw-runner/agaw-runner.sh under the QM directory.

This file must be edited to set its running parameters, that are:

JAVA=/usr/local/queuemetrics/java/bin/java

Path to the java virtual machine. Please point to a SUN JDK version 1.4 or newer. The default path points to the default JDK that comes with the automatic QueueMetrics installation.

VMOPTS=-server -Xmx256M -Xms256M

The options for the Virtual Machine. Should be okay for most servers.

USER=demoadmin
PASS=demo

The username and password of a user the transactions will be run under. This should be a regular user or an administrator with visibility to all queues to be selected.

JDBC="jdbc:mysql://10.10.3.5/qmueuemetrics?zeroDateTimeBehavior=convertToNull&\
  jdbcCompliantTruncation=false&user=queuemetrics&password=javadude"

The JDBC URL to connect to the same database as the main QueueMetrics instance (see your web.xml file).

QMPATH= /usr/local/queuemetrics/webapps/queuemetrics-1.5.0

The system path to the local QueueMetrics installation. You can find it on the local Licence page.

ITER=3

The number of iterations that will be run by the Java process before terminating and spawning a new Java process. This is done so that there is no problem with potential memory leaks, as the JVM is periodically rebuilt. A higher ITER count means more iterations using the same JVM and avoids the burden of reloading classes and libraries.

IDLE=2000

The idle time in milliseconds between one interaction and the other.

RUNLOG=false
RUNLOGDIR=/root/runlog

If RUNLOG is set to TRUE, a detailed run log will be created under the RUNLOGDIR. This directory must be writeable by the Java process and MUST be cleaned periodically - enabling this feature causes a lot of information to be written. See Section 18.13.4, “Debugging with Runlogs”.

QMARCH=$JARLIB/loway-tpf-155p.jar
QMJAR=$JARLIB/QueueMetrics-1.5.0.jar
REDRPC=$JARLIB/redstone-xmlrpc-1.0.jar
MYSQLJAR=$JARLIB/mysql-connector-java-3.1.10-bin.jar

These are the names of the Java classes bundles that contain the local version of QM and of its TPF architecture. These must match the ones under WEB-INF/lib or you will get "Class not found" errors on startup. In a standard QueueMetrics release, QMARCH and QMJAR items are correctly set by the build system to match the current JARs.

SERVLET=/usr/local/queuemetrics/tomcat/common/lib/servlet-api.jar

This points to the servlet API used by your Tomcat installation. The default path is okay for a standard QM installation.

Once you set everything up, you can simply set the script executable and start it to see its output.

chmod a+x agaw-runner.sh
./agaw.runner.sh

Please note that the script will loop indefinitely, so it must be stopped through a kill -9 command.

# Oldest obsolete run to keep when running an optimization, in minutes
dbmaint.agaw_oldestRun=30

# Oldest obsolete log to keep when running an optimization, in minutes
dbmaint.agaw_oldestLog=30

# Oldest obsolete broadcast entries to keep when running an optimization, in minutes
dbmaint.agaw_oldestBroadcast=180

wget http://server/qm/qm_sys_optimize.do?O_L=user&O_P=pass&O_C=AGC

client.refresh=7000

client.sparkurl=http://chat.myserver:9090/webchat/jivelive.jsp

client.sparkuser=supervisors@workgroup.chat

# License key for the Agaw Runner
runner.activation=............................

18.13.4. Debugging with Runlogs

Runlogs are text files that contain the very details calculations for each run are based upon, so they make it possible to spot from where the figures displayed in the AGAW browser come from.

In order to run this, it is necessary to:

• Enable this feature in the agaw-runner.sh script
• Create a cron job to delete the generated files, e.g. nightly or weekly, as the result is extremely verbose
• Make it possible for the administrative users to fetch the files remotely, e.g via a WinSCP client

When this feature is turned on, when administrative uses happen to find some incorrect data, they should:

• Take a screenshot of the incorrect data
• Write down the run-id
• Fetch the text file called agawrun_XXXXX.txt that is under the RUNLOGDIR directory, where XXXXX is the run-id

The run-id can be found as shown here: