• You need PERL and basic knowledge on how to use Asterisk, if you want to learn Asterisk start here and come back later.
• You have to add a user to asterisk's manager.conf and reload asterisk for the changes to take effect.
• For better compatibility you should use Asterisk 1.2. Most functionality is available in Asterisk 1.0 but with some glitches.
• You also need to define in your dialplan the conferences in a proper way and in their own context, as explained in op_server.cfg comments and here.
• If you plan to use the "Info" box to set the callerid text when transferring or originating a call, you need to modify your dialplan. See extensions.conf.sample
• You also need to be wary, as English is not my first language.

Download the latest version (look at the top-right corner on your screen). Untar the source: (tar zxvf filename-you-downloaded.tgz), cd into the directory and read all the files with uppercase names (README, FAQ, etc).

Copy the files in the flash subdirectory to a suitable place on your web server. If your web root is /var/www/html, you can create a subdirectory 'panel' (mkdir /var/www/html/panel) and copy the files there (cp flash/* /var/www/html/panel).

In order to run, you have to configure some aspects of Asterisk and the panel itself to suit your needs/environment. The bundled configuration files are examples only, they won't match your Asterisk setup. So please take the time to read the docs and examples and familiarize yourself with the configuration.

Flash Operator Panel consists of two parts, a server and a client. The server connects to the Asterisk Manager port and acts as a proxy between the flash client and Asterisk. The flash client connects to FOP proxy server (op_server.pl) and speaks its own protocol to reflect status changes and send control commands to asterisk.

Op_server.pl speaks to asterisk trough default port TCP/5038. Flash clients connect to op_server.pl though default port TCP/4445. Both ports can be changed in their respective configuration files. Understanding the architecture will help you troubleshoot connectivity problems later on.

The config file for the panel server is op_server.cfg where you define basic and fundamental aspects of your setup, as login credentials, security codes, extensions and contexts, directories, etc. The config file for the flash client is op_style.cfg where you define mostly visual aspect of the flash side, like button sizes, icon positions, font family and size, etc.

Make sure you have a user with privileges for the asterisk manager. Just edit /etc/asterisk/manager.conf and add one if you have not done it yet.

;
; Asterisk Call Management support
;
[general]
enabled = yes
port = 5038
bindaddr = 127.0.0.1
 
[myuser]
secret = mysecret
deny=0.0.0.0/0.0.0.0
permit=127.0.0.1/255.255.255.0
read = system,call,log,verbose,command,agent,user
write = system,call,log,verbose,command,agent,user

You should set up ACLs right in manager.conf to restrict access to it. Then reload asterisk and be sure to open port 5038 in your firewall if you need it to. If op_server.pl will run on the same machine, then it is best to connect via localhost. If you set ACL to only allows access to localhost (127.0.0.1), then be sure to use that same IP address in your op_server.cfg file.

You can also set up read and write permissions for the manager.. in order to have a full working operator panel, set the read and write permissions as the example above.

Edit op_server.cfg and change the appropriate parameters for your setup.

transfer_timeout="0,No timeout|300,5 minutes|600,10 minutes"

[conferences]
exten => 900,1,MeetMe(900)
exten => 901,1,MeetMe(901)
exten => 902,1,MeetMe(902)

[rooms]
conf => 900
conf => 901
conf => 902

Edit op_buttons.cfg to suit your needs. The syntax is similar to asterisk configuration files.

You have to configure the buttons you want displayed on the panel here. Any channel name not defined here will not be shown.

[ZAP/4]
Position=1
Label="11 Reception"
Extension=11
Context=local
Icon=1
Mailbox=11@localvm
URL=mypage.php
Target=myframe
;No_Rectangle=true

The channel name is writen between brackets. Depending on the channel name and Position header you will select the type of button. The sintax for SIP channels is SIP/username. For ZAP is ZAP/channelnumber. For IAX2 is IAX2/username. Other channels follow similar rules. As I don't have the hardware, I couldn't test with other channel types. You can set the debug to 1 and look for the channel names comming from Asterisk to match yours. There are also special button types for particular situations and applications, like meetme buttons, park button, queue buttons, regexp buttons, etc.

Position is the button number. Buttons are drawn from top to bottom and from left to right. The total number of buttons depends on the size of the buttons and the padding (you can change those values in op_style.cfg). You can put an exact value, a comma separated list, a range, or the special 'n' (next) value. If a button has more than one position defined, it will be treated specially: if it's for a regular channel, it will become a trunk button, if it's for a special button it will change the behaviour/type. See button types for details:

Panel_Context Starting from version .10, you can have panel 'contexts'. This means only one server running, and several flash clients with different buttons layouts connected to this unique server. If you omit this parameter, the 'default' context will be asumed. To specify the context to load in flash, you have to modify the page that loads the swf file. Just add '?context=mycontext' after every appearance of 'operator_panel.swf'.

URL if set, the button label will become an hyperlink that links to this URL when clicked.

Target to set the hyperlinks target. If omited, it will use the current window. You can use the standard html targets, like _parent, _new, etc.

No_Rectangle if set to true, the rectangle will not be drawn, only the other elements (label, icon, caller id, timer, etc). You can use your custom background image to draw your own buttons.

Label is the button label. You have to enclose it with quotes if you plan on using spaces.

International Characters

If you want to display foreign characters in button labels, you have to save the configuration file with UTF-8 encoding. To convert the file to UTF-8 utilizing vi and the command line just perform:

vi -c ":wq! ++enc=utf8" op_buttons.cfg

Note that the button label is used as the caller id text when originating calls within the panel. If you use international characters, the caller id will be mangled and not displayed correctly in your user agent.

Server from version 0.20 onwards, you can monitor multiple asterisk servers. If the channel for a button belongs to another server instead of the first one, specify its number.
Extension is the extension number. It must be defined in your dialplan to reach that channel. If there is no extension for that button (eg: its an external line) you must set it to -1, this way, the server will discard attempts on transfers to that channel.

Context: if the extension is not reachable from the default context in your dialplan, you should also specify its context. If you have extension number 100 inside the 'from-sip' context, then you should write 100 for the extension and from-sip for the context.

Icon is the icon. There are six icons available:

Icon 1	Icon 2	Icon 3	Icon 4	Icon 5	Icon 6

If you don't want to show an icon on a button, set it to 0 or just delete the Icon line for that particular button.

Mailbox is the voicemail mailbox to monitor. If you have voicemail accounts for the extension, you have to specify the voicemail user and context. If you leave this field empty, the server will not check the mailbox for that extension.

[900]
Position=1
Label="Meetme Room 900"
Extension=900
Context=conferences
Icon=6

[900]
Position=2-5
Label="Meetme User"
Extension=-1
Icon=6

[QUEUE/sales]
Position=2
Label="Sales Queue"
Extension=3
Context=queues
Icon=5

[QUEUE/support]
Position=3-10
Label="Support Queue"
Extension=-1
Icon=5

[QUEUEAGENT/sales]
Position=3-10
Label="Sales Queue"
Extension=-1
Icon=3

[AGENT/1002]
Position=12
Label="Agent 1002"
Extension=1002
Context=Agents
Icon=3

[PARK/701]
Position=12
Label="701 Park"
Extension=701
Icon=0

[CLID/5555555]
Position=13
Label="5555 John"
Extension=5555555
Context=from-internal
Icon=2

[_SIP/.*]	; regexp to match all sip channels
Position=1,2,3
Label="All Sip channels"
Extension=-1

[ZAP/4]
Position=1
Label="11 Reception"
Extension=11
Context=local
Icon=1
Mailbox=11@localvm

[SIP/12]
Position=2
Label="12 Mary"
Extension=12
Context=local
Icon=1
Mailbox=12@localvm

[IAX2/david]
Position=3
Label="13 David"
Extension=13
Context=local 
Icon=2
Mailbox=13@localvm

[CAPI[contr1/NNNNNNNNN]] 
; where NNNN is the ISDN number. 
Position=4  
Label="External CAPI"
Extension=-1
Context=in-extern
Icon=4

[IAX2/iaxtel]
Position=10-12
Label="Iaxtel"
Extension=-1
Icon=3

[SIP/myprovider]
Position=20-30
Label="SIP TRUNK"
Extension=-1
Icon=4

Edit op_style.cfg to change the visual layout. You can change the button size and colors, icon placement and size, etc. DO NOT modify the variable names, just the value after the equal sign and DO NOT use spaces. With proper adjusting, you can have more than a 100 buttons on the screen.

The variable names are self explanatory. For example, if you want to reduce the height of the buttons, just set btn_height to a lower value.

You can change this file with the op_panel.pl running. After changing a value, you must tell the server to refresh the configuration by sending a HUP signal (killall -HUP op_server.pl). After that, you need to reload the flash display, by clicking the reload button or just reloading the page.

You can change the toolbar layout by changing the number after the variables show_???. Each one represents a possible element in the toolbar.

show_security_code	Security Code input box
show_clid_info	Extra Info in CLID box
show_btn_help	Help button
show_btn_debug	Debug button
show_btn_reload	Reload button
show_status	Status Bar

A value of 0 disables the element. A number represents the order in the toolbar it will be displayed, number one being the leftmost part of the toolbar. In the example configuration, all the toolbar elements are displayed in correlative order. Eg: if you do not want to display a DEBUG button, set the 'show_btn_debug' to 0. You can translate the text of the toolbar in the corresponding variables.

If you want to set the caller id text from the flash applet when transferring a call, you will have to modify your dialplan, or standard extension macro, to something similar to this:

[macro-stdexten]
# Example standard extension macro for setting the
# callerid if the info was supplied from the operator
# panel. The panel sets a database entry for the 
# channel name with the caller id text.
#
# If the variable does not exist in the database
# (if was not set by the operator panel) the line
# 1 jumps to priority n+101, to perform a normal
# dial without setting the CallerIDName
 
exten => s,1,DBget(temp=clid/${ARG1})
exten => s,2,SetCIDName(${temp})
exten => s,3,DBdel(clid/${ARG1})
exten => s,4,Dial(${ARG1},30,TrH)
exten => s,5,Voicemail(u${MACRO_EXTEN})
exten => s,6,Hangup
 
; gets here if dbget fails (there was no 'clid info' provided)
exten => s,102,goto(s,4)
 
; busy from dial
exten => s,105,Voicemail(b${MACRO_EXTEN})
exten => s,106,Hangup

If you don't want to mess with the caller id, be sure to set the show_clid_info to 0 in op_style.cfg and skip this step.

You can also use the UserEvent asterisk application from your dialplan to trigger some special actions or behaviours.

PopUps: you can fire a screen popup from the dialplan. The button parameter is optional, it will restrict the popup to flash clients loaded with mybutton or restrict set to that button number. Example:

exten => 1,1,UserEvent(FOP_Popup|URL: p.php?e=${EXTEN}^Target: top^Button: 1)

Change led color: you can change the led color too (but the state will not be saved between reloads):

exten => 1,1,UserEvent(FOP_ledcolor|Color: 0x0000FF^State: 0)

The color can be any hex value. The State is:

• 0 for available status (channel not in use)
• 1 for busy status (channel in use)
• 2 for agent status (channel not in use and logged in agent)

Be sure to set the executable bit in op_server.pl if not set (chmod a+x op_server.pl). And check the location of your perl binary. It is assumed to be /usr/bin/perl. If it is not, modify the path in op_server.pl. To run the server just type in the same directory as the file itself:

./op_server.pl

The server does not detach from the console. If you want it to run in the background daemonized, append '-d' in the command line. If the debug level is other than 0, the output will be logged on stdout. To find out if the server works well, set the debug level to 1, the output should look like this:


<- Asterisk Call Manager/1.0
<- Response: Success
<- Message: Authentication accepted
<-

You can run the server from your rc.local script to have it running on startup. There are also example init scripts in the init directory if you prefer to use your distro init system. Be sure to start op_server.pl after asterisk. If you restart asterisk, the op_server will try to reconnect 60 times with 10 seconds intervals (10 minutes). If it fails to connect after these many attemps, it will shutdown.

Just point the browser to the directory where you placed the html and swf files. You should see something similar to the live demo

When a channel is busy, or there is someone in a conference or queue, the oval will be red. If it is available or there is nobody on the queue or conference, it will be green. A flashing oval indicates ringing. If all the ovals are flashing, its because the flash applet lost connection from the op_server.

When your mouse is over a button, and there is activity going on for that button, you can see the details on the status bar.

Before performing actions, you have to enter the Security Code in the box. If the code does not match, your actions will be ignored. After typing the code, you can:


• Hangup a channel: (double click the colored dot on the button)
• Transfer a call leg via drag&drop (drag the phone icon on a talking button to another button)
• Originate calls via drag&drop (drag the phone icon from one available button to another available button)
• Barge in in a call via drag&drop (drag the phone icon from one available button to a bridged/busy one)

CRM stands for 'Customer Relationship Manager'. You can use the Flash Operator Panel in a call center environment and integrated with a web based CRM software. This feature of the panel lets you load a web page based on the callerid of an incomming call.

You can have a web page with all the customer details before answering the phone.

This feature was introduced in version 0.11 of the Panel. To set it up, you have to specify some variables in the html page that loads the flash operator panel:



mybutton	The button number of the extension you like to monitor
url	The URL to call when the above extension is ringing
target	The target frame or window where the URL will be loaded (if you leave it blank, it will use '_self')


When a call comes in for the button monitored (mybutton), it will open a browser window pointing to url in the target. It will use method get to send the variable clid to that url, so you can perform your search for the customer record.

You have to add the variables when loading the .swf file. Open the index.html supplied and look for all the instances of operator_panel.swf and append the variables like:

operator_panel.swf?mybutton=4&url=customer.php&target=bottom

You can use an invisible frame (0 width and no borders) to load the .swf file and not clobber the screen with the panel itself if you want. To have a different button monitored, user logins, etc, you can use the method of your choice: php,modperl,asp, etc, to modify the frame that loads the swf file and set the variables accordingly. If you do not specify a mybutton variable, or if the url is empty, the CRM feature will be disabled.

An example customer.php should be like:


<?
if(isset($_GET['clid'])) {
  echo "The caller id is ".$_GET['clid'];
}
?>

FOP can monitor the status of queues and agents of an Asterisk PBX. There are several ways on Asterisk to handle queues, each one has its own 'way', so it does the Flash Operator Panel.

The agent features in op_server.cfg are:


• rename_label_agentlogin
  If you are using Agentlogin in your Asterisk setup, you can change the Label of a button to the Agent number or name (see rename_to_agent_name below) when they log in to the system. The button renamed will be the one corresponding to the channel used by the Agent to login.
  
• rename_label_callbacklogin
  Another way to setup Agent on Asterisk is by using Agentcallbacklogin. The events used by the two applications are different, so you have to turn this one on if you are using callback logins instead of regular agent logins. The result is the same, but the way it works its different: Agentcallbacklogin return a call to an extension@context specified in its parameters. FOP will match a button for callbacklogins based on this extension@context, they will match the Extension and Context parameter for a button definition.
• rename_to_agent_name
  If you set this one to 1, the label will be renamed to the full name of the agent specified on agents.conf instead of the agent number.
• rename_queue_member
  Another way to handle queues is by ways of AddQueueMember/RemoveQueueMember. As this option does not generate a manager event, you will have to modify your dialplan to generate the needed events so FOP can display their status. For example:
  
  
  exten => 1000,1,Answer
  exten => 1000,2,AddQueueMember(myqueue|SIP/${CALLERIDNUM})
  exten => 1000,3,UserEvent(Agentlogin|Agent: ${CALLERIDNUM})
  exten => 1000,4,Playback(agent-logged)
  exten => 1000,5,Hangup
  
  exten => 1001,1,Anser
  exten => 1001,2,RemoveQueueMember(myqueue|SIP/${CALLERIDNUM})
  exten => 1001,3,UserEvent(RefreshQueue)
  exten => 1001,4,Playback(agent-loggedoff)
  exten => 1001,5,Hangup
  
  
  
• change_led_agent
  If you set this option to one, the LED of the button corresponding to a logged on agent will change its color to led_color_agent (specified in op_style.cfg)
When a button corresponds to an Agent, if you double click on the little arrow for that button, you will see the number of calls taken for each queue the agent is member off. If you double click on the little arrow for a queue button, you will see statistics about that queue, like total number of calls taken, missed, average hold time, etc.