docs.loway.ch :: Loway Documentation Center

Asterisk tools

Uniloader is able to perform maintenance operations on the queues of an Asterisk system.

As many tools use a regexp to identify a set of agents, you can use the Regexp tester to develop custom regular expressions easily.

Queue-Add: add an extension to some or all queues

This command lets you log on an agent (with optionally an hotdesking extension and/or a separate state interface) on a set of queues as specified by a regex.

This way Uniloader will:

connect to Asterisk and fetch the list of availble queues
select all those that match the given regexp
add the member to all those queues.

Like other Asterisk subcommands, it supports a "dry run" mode where you can see what the command would do without actually doing it.

For example, running:

uniloader asterisk queue-add
  --queues ".+"
  --agent SIP/101
  --host 127.0.1 --login qm --secret 1234
  --dry-run 0

will add member SIP/101 to any queue on the system.

Running instead:

uniloader asterisk queue-add
  --queues "3.."
  --agent agent/101
  --hotdesking  PJSIP/203
  --host 127.0.1 --login qm --secret 1234
  --dry-run 0

will create a hot-desking record specifying that Agent/101 is working at extension PJSIP/203, and will add that extension to all three-character queues starting with "3".

Full invocation:

NAME:
   uniloader asterisk queue-add - Add an agent to one or more queues.

USAGE:
   uniloader asterisk queue-add [command options] [arguments...]

DESCRIPTION:
   Adds an agent to one or more existing queues, handling
hot-desking and presence.


OPTIONS:
   --queues value, -q value      A regexp that details which queue ids to match, e.g. '^3..$' or '.+' for all
   --agent value, -A value       An agent ID or channel, e.g. Agent/101 or PJSIP/1234
   --hotdesking value, -H value  A channel the agent is hotdesking on, e.g.  PJSIP/1234 or Local/123@from-internal/n
   --presence value, -p value    A device to use as a StateInterface, e.g.  PJSIP/1234
   --host value                  Your Asterisk server (default: "127.0.0.1")
   --port value                  The AMI port on Asterisk (default: 5038)
   --login value                 The AMI user as defined in manager.conf
   --secret value                The AMI secret [$AMISECRET]
   --dry-run value, -d value     When 1, this is a dry run. Set to 0 to perform changes on the PBX. (default: 1)

Queue-Kick: log-off all (or some) users

This command lets you log off some (or all) agents, from some (or all) queues, at a given time.

This is useful to avoid agents that "forget" to log off and remain logged in at all time, therefore impacting agent presence statistics. Their presence also impacts queues, as the queue will always think that there is someone ready to serve calls even if they are not there anymore, and will keep callers waiting uselessly e.g. at night.

Agents are unpaused before being logged off.

This is also useful to forcibly log off agents that managed to log in using impossible extensions or agent codes, in this case it can be run manually on demand or, for the hardest cases, scripted to run every few minutes to forcibly resolve such cases.

By using a regular expression for queues and/or agents, you can target a set of specific entities, e.g. all queues that start with 3, or all agents with a space in their name.

For example:

^3..$ will match all codes that start with a 3 followed by two other characters
^(301|302)$ will match queues 301 or 302 but not 303
^\d\d$ will match any two-digit code like "12", or "34", but not "A7"
^.?/\d$ will match any agent like "SIP/123" but not e.g. "SIP/123a4"
^(?i)sip/\d+$ will do a case-insensitive, with match SIP/123 or sip/123

When writing regular expressions, we suggest always add the start and end line anchors (^ and $), otherwise a partial match will be enough to trigger inclusion, and to enclose the expression within your shell’s single quotes.

In any case, when you run the command, it will be in dry-run mode; so it will print out the changes that it would do, but won’t perform them. To have the command actually do changes, call it with --dry-run 0.

For example, if you run:

$ uniloader asterisk queue-kick --host 1.2.3.4 --dry-run 0
Connecting via AMI to 1.2.34:5038 - Username '' secret '****'
ACTIONS PERFORMED: 3

* Agent SIP/265
  #1   - Leave Queue 300                        OK
  #2   - Leave Queue 301                        OK
  #3   - Leave Queue 400                        OK

All agents on all queues will be logged off, and it will print a recap of the actions that were performed.

Full invocation:

NAME:
   uniloader asterisk queue-kick - Removes agents from queues

USAGE:
   uniloader asterisk queue-kick [command options] [arguments...]

DESCRIPTION:
   Removes all agents matching the agent/queue filters
specified as regular expressions on the command line.

This is meant to be run  as a cron job at the end of the work day.


OPTIONS:
   --queues, -q   A regexp that details which queue ids to match, e.g. '^3..$'
   --agents, -a   A regexp that details which agents to match, e.g. '^SIP/\d+$' or '^.+?/523$'
   --host "127.0.0.1"   Your Asterisk server
   --port "5038"  The AMI port on Asterisk
   --login     The AMI user as defined in manager.conf
   --secret       The AMI secret [$AMISECRET]
   --dry-run, -d "1" When 1, this is a dry run. Set to 0 to perform changes on the PBX.

Queue-Replicate: replicate presence events

Queue-Replicate is an extension of Queue-Kick, that is, it will log agents off from a queue and will then log them back in, unser the same name and state interface, and paused if they are.

This is useful because sometimes you just want to replicate the current agent state soon after midnight, so that the Real-Time page of QM appears with the correct agent presence even when agents had no call yet for the day. In this case you create a cron-job like:

# At one minute past midnight, replicate Asterisk presence
1      0       *       *       *       uniloader asterisk queue-replicate --dry-run 0

While this is not something we suggest (if an agent is always logged on then their presence information is meaningless), sometimes smaller sites do not really care about agent productivity and want agents to always remain logged on.

This does not work correctly if your QueueMetrics runs in hot-desking mode, as hot-desking events are not correctly replicated.

Full invocation:

NAME:
   uniloader asterisk queue-replicate - Replicates agent presence events

USAGE:
   uniloader asterisk queue-replicate [command options] [arguments...]

DESCRIPTION:
   Removes agents from queues as specified by the agent/queue
filters and then adds them in again, so that agent presence events
are replicated on the queue_log.

This is meant to be run as a cron job soon after the midnight, so that
agents that do not log in every day still appear on  the real-time page.

DO NOT USE if you are running in hotdesking mode, as hotdesking agents
will not be replicated correctly.

OPTIONS:
   --queues, -q   A regexp that details which queue ids to match, e.g. '^3..$'
   --agents, -a   A regexp that details which agents to match, e.g. '^SIP/\d+$' or '^.+?/523$'
   --host "127.0.0.1"   Your Asterisk server
   --port "5038"  The AMI port on Asterisk
   --login     The AMI user as defined in manager.conf
   --secret       The AMI secret [$AMISECRET]
   --dry-run, -d "1" When 1, this is a dry run. Set to 0 to perform changes on the PBX.