Configuring the GNU Gatekeeper ACD

Starting the ACD

The ACD is a Java console application. It can be started with

java org.gnugk.acd.GnuGkACD

Shell scripts for Unix (GnuGkACD.sh) and Windows (gnugkacd.bat) that do just that are provided.

To run, you need a Java virtual machine. I have tested with Blackdown and Sun Java 1.4.1 on Linux and Sun Java 1.3.1 on Windows. Other virtual machines, starting with Java 1.2 will will probably work, too. Microsofts JView only supports Java 1.1 and will not work.

The ACD will write a minimal log to the console and can be stopped by pressing Ctrl-C.

GnuGk Configuration

GnuGk has two configuration parameters for virtual queues:

[CTI::Agents]
VirtualQueue=support,sales
CTI_Timeout=10

The first tells GnuGk which groups you have and the second is the time in seconds the ACD has to answer RouteRequests from the gatekeeper. 5 - 10 seconds should be enough as a time-out when you only use queue mode REJECT. Otherwise set the CTI_Timeout at least as high as the highest queue timeout.

To enable virtual queues, add the 'vqueue' policy to your routing policies:

[RoutingPolicy]
default=vqueue,explicit,internal

Also make sure the ACD application is allowed to connect to GnuGk's status port. For example:

[GkStatus::Auth]
rule=explicit
127.0.0.1=allow
default=forbid

ACD Configuration

The configuration is stored in two files that must be placed on the CLASSPATH:

ACDConfig.properties		for general settings
ACDAgentConfig.properties	for agent / group configuration

Example ACDConfig.properties:

# Config file for GnuGkACD
#
gnugk_host=127.0.0.1
gnugk_port=7000
listen_port=7001
distribution_algorithm=LONGEST_IDLE
sanity_interval=90
logfile=acd.log
debug=0
redir_location=http://www.company.com/
#
# config setting for certain queues
#
unimportant_queueing_mode=REJECT
support_queueing_mode=RINGING
support_priority=10
support_ring_timeout=30
support_size=1
sales_queueing_mode=RINGING
sales_priority=50
sales_ring_timeout=60
sales_size=-1

Apart from the obvious access to the GnuGk status port, you must configure a listen_port for the ACD where it can receive login and logout commands for agents and a possible redirect location (see below).

You can specify a sanity_interval when all agent states in the ACD will be refreshed with current states from the gatekeeper in case the 2 systems got out of sync. This can happen when the ACD orders call transfers that fail for some reason. A value of 0 or below turns this feature off. Is off by default. You should not set this valkue too low, beacuse on a busy ACD this will result in a high work load. Use this feature only with GnuGk 2.0.7 and above, older versions may crash the ACD.

The specification of a logfile is optional. If none is specified the output goes to the console. The current configuration of the ACD is always printed on the console on startup. All output after that goes to the file.

Currently three distribution algorithms are supported:

LONGEST_IDLE    choose an agent who is suited for this group, and
                has been without a call the longest (fair)
ROUND_ROBIN     give work to the next agent who is suited (fair)
FIRST_FIT       give the call to the first suited agent that is
                found (unfair, but fast)

Some setting apply ony to a certain queue. The have the form

QUEUENAME_queueing_mode=...
QUEUNAME_priority=...
QUEUNAME_ring_timeout=...
QUEUNAME_talk_timeout=...
QUEUENAME_size=...

For each queue you can define with QUEUENAME_queueing_mode= how it will handle calls when no agent is available right now:

REJECT          reject the call (default)
RINGING         keep the call rining until an agent becomes
                available or the timeout is reached
TALKING         let the caller hear announcements until an agent
                becomes available
                This works only with a gatekeeper in routed mode.

QUEUNAME_priority defines the importance of the calls to this queue. When an agent becomes available he will handle calls to queues with the highest priority first. Default is 0.

QUEUENAME_ring_timeout defines how long a call to this queue will be kept in RINGING state until it is rejected. Default is 60 sec. QUEUENAME_talk_timeout defines how long a call to this queue will be kept in TALKING state until it is rejected. Default is 1 hr.

QUEUENAME_size lets you specify a maximum number of unanswered calls that will be held for this queue. If more calls come in they will be rejected. Default is unlimited size.

To configure what agent can work for which group, we have to put one line for every agent into ACDAgentConfig.properties in the form agent=group1,group2.

The name for the agent must be his first H.323 alias which he uses to register with GnuGk! Please don't put spaces anywhere in the agent config lines. Since the agent names and the group names are also used as H.323 aliases they are all case-sensitive.

Example ACDAgentConfig.properties:

# list of agents: alias=group1,group2
#
jan=support
willi=sales,support
frank=sales

Talking wait queues

In a "talking wait queue" calls waiting for an agent are transfered to an endpoint that may play a continous message. When an agent become available the call is transferred automatically to that agent.

For talking wait queues to work, the involved endpoints must support GnuGk's implementation of TransferCall, that means they must honor the Facility message. OpenH323 endpoints like openam and ohphone do so, as does EnVison 2.2 (Radvision H.323 stack) and many other endpoints. Others, like Netmeeting, don't support this.

You can use OpenAM endpoints to play the message. The ACD assumes that you have started enough talking endpoints for all the the waiting positions in your queues. The endpoints must have an H.323 alias QUUENAME_wq_NUMBER.

Example:
If you have a talking wait queue of size 2 for a queue called support, you have to start 2 endpoints that register with GnuGk, one with alias support_wq_1 and one called support_wq_2.

Agent Login / Logoff

As a default all agents are available for ACD work as soon as they are registered with GnuGk. When an agent has other work to do he can either unregister form GnuGk, or he can Logoff from the ACD and login again later.

To do so, you can use the provided PHP script (note the config settings at the top of the script) or you can point your browser to the listen port of the ACD.

For example you can open "http://127.0.0.1:7001/logout?frank" to logout from the ACD. Your browser will be redirected to the redirect_location from the config file. If you don't need the redirection, you can use an application that calls this URL. The PHP example (acd_login.php) ignores the redirect.

In a production setting, it probably wouldn't be advisable when every agent can login / logout every other agent. This functionality should rather be incorporated into other applications that the agents are using.

Debugging Agent / Pending Call Status

You can open "http://127.0.0.1:7001/status" in a web browser to view the current list of agents in the ACD and see their states. You will also see a list of pending calls.

Known Problems

agent states should really be stored stored in a database, so they are not lost on ACD restart and are available for statistics
there should be a check if agents accept the calls routet to them, the sanity checks reduce this problem, but there should be better ways

Last updated: 30. Mar 2008
Page maintained by Jan Willamowius