Monday, April 19, 2010

Avaya PBX admin web service

At the UW we've been heavily invested in Avaya telecommunications products for nearly two decades. In particular, we've been invested in the DEFINITY platform, now called Communications Manager (CM). We started using CM when it was owned by AT&T. It was later acquired by Lucent and then separated to become Avaya.

CM is the cadillac of enterprise phone systems (PBX) with almost every feature imaginable. Like many enterprise vendors, they provide GUI applications written for Windows and they work fine--if they have the features that you want to use. Once you want to start integrating with other enterprise systems and automating tasks, you run into situations where the provided tools hinder work more than they help.

The primary interface to these PBX systems is with a terminal. Originally it was a serial terminal but now telnet and ssh are available. When you log in you select a "terminal type." Most people use the screen-based VT220 interface where you type commands and use tab and return to move around the screen to make changes. It's not fun to use those screens for scripting, but there's another undocumented terminal type called "OSSI" that's designed for scripting and is used by Avaya's own GUI tools.

In this post I'll describe the web service system I've built around the OSSI terminal connection. The end result is contained within a Perl module that comprises the heart of this system.

The system breaks down into three parts:
1. DEFINITY_ossi.pm
2. A separate PBXD server instance for each PBX.
3. A single web CGI interface that passes XML requests between the client applications and the correct PBXD instance.

DEFINITY_ossi.pm is the Perl module that knows how to connect to all of our PBX systems, process commands, and return data either formatted like the output of the VT220 screen or as a set of OSSI fields.

PBXD is a server based on the Net::Server::PreFork CPAN module that manages a pool of connections to a single PBX and provides an XML interface to DEFINITY_ossi.pm. There is 1 instance of PBXD running for each of our 3 PBX systems. Each PBXD instance has its own config file.

Finally the web interface is a Perl CGI script that knows about each PBXD instance and proxies the XML requests from clients to the specific PBXD instance for each PBX.

Here's a visual description of the system


Once it's setup and deployed you have a scalable platform for rapid development of web applications to manage all of your PBX systems. We've moved both batch and interactive application to the new system and it's been working well. I hope you've found this post interesting and that it will give you some ideas and code that can help manage you own PBX systems.

26 comments:

  1. Wow wow wow wow wow wow wow wow wow wow! Ben, that's fantastic! I've been hunting for any OSSI documentation for years and there it is, ready Perl module implementation, just like Christmas present! Thanks a bunch!

    P.S. By the way, do you have any docs on OSSI protocol or that was all reverse engineering?

    ReplyDelete
  2. Thanks for the flattering comments. It was all reverse engineering mostly based on packet captures and a bit of guessing. I've heard rumors of there being real documentation.

    ReplyDelete
  3. This system is quite impressive. Have a bit of a problem attempting to get it running.

    getting connection parameters for n1
    ERROR: unknown PBX [n1]. Config must be added to config file pbx_connection_auth.xml before it can be used in production.
    Can't call method "get_node_name" without a package or object reference at ./pbxd line 41.
    -- child init hook --

    suggestions?

    ReplyDelete
    Replies
    1. Did you ever get around this? I have the same problem even though I have it defined in pbx_connection_auth.xml.

      Delete
    2. I'd guess it's having trouble finding your pbx_connection_auth.xml file. The default is looking in the working directory, probably the home dir of the user running it. But you could always change it in the DEFINITY.pm file.

      Delete
    3. It definitely finds the configuration file because when I didn't have it in the home it errored because it couldn't find the file and then I moved it to my home directory and then it gives this error. I've tried with name="n1" and name="g3" since all the examples were around n1 and it won't find the pbx entry either way. My file looks like this:





      Even running pbxd with --debug doesn't yield additional output of the errors. The /var/log/pbxd.log file just contains the child init hook message.

      I'm using perl 5.16.3 on OpenBSD 5.4. Any help is appreciated as this looks like a great tool to be able to automate routine changes!

      Delete
    4. The name is just a name, so if you're consistently using the same name then it should work. The name is in a few other files too and they should match. Maybe XML::Simple isn't able to parse your config line. I've been tripped up by reserved XML characters in the password before, maybe that's it?

      Delete
  4. Is this being maintained? Will it work with Communications Manager 6.1?

    ReplyDelete
  5. I did much of the same reverse engineering work [with Wireshark] to create a CLI utility to perform various batch functions. Great job taking that to the next level with a web interface!

    ReplyDelete
  6. Kev: It looks like the error means you need to put the login credentials and pbx name in the pbx_connection_auth.xml file.

    ReplyDelete
  7. Thanks Sam! It's great to hear that someone else has dug into the OSSI protocol too. And for anyone else wondering it's still working in latest CM versions and in Avaya Aura.

    ReplyDelete
  8. Ben: Thanks for the solution, But I didn't understood the way you connecting between web interface and PBXD.

    When i run, I got the following error please suggest:
    Could not connect to pbxd server on 10.129.95.12: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond.

    ReplyDelete
    Replies
    1. Could be a number of things. But I'd start with making sure the ports in the web cgi script match the ones you have the pbxd instances listening on.

      Delete
  9. Hi Ben,

    Do you happen to have screenshots and perhapes instructions on getting this installed and configured ?

    Thanks

    ReplyDelete
    Replies
    1. I haven't created any documentation like that yet. I'm currently on the trail of a bug that occasionally requires me to manually restart some pbxd instances, and I've added log4perl to help collect data. Once I've fixed that I'll update the release the new code and hopefully I'll find time to add some installation instructions. The configuration settings can be found at the top of each perl file, where you can adjust the file locations and the list of pbx systems and ports that the pbxd instances listen on.

      Delete
  10. Thanks Ben for Your work ,sorry but I have some problem to deploy it .
    I copied into a cgi subfolder the pbxd.pl , pbxd-n1.conf , Definity_ossi.pm , pbxd.cgi and pbx_connection_auth.xml.
    When I submit the page I receive :
    Could not connect to pbxd server on 10.81.3.10: Connection refused

    Thanks in advance

    ReplyDelete
  11. I've moved all the code for this to GitHub and updated the links in the post. Hopefully that will be a better place for it.

    ReplyDelete
  12. What would be the format with $node->pbx_command when submitting data with the change command? i.e. I want to set the port of a station (8004ff00) to X

    ReplyDelete
  13. The examples in the code show display commands and changing stations is just like displaying them. So the xml command would look something like this.

    <command pbxName='n1' cmdType='ossi' cmd='change station 12345' verbose="true">
    <field fid='8004ff00'>X</field>
    </command>

    ReplyDelete
  14. Hello Ben ,
    Could You give some info about a modem/datamodule connection , how have I to config the pbx_connection...xml file ???
    Thanks

    ReplyDelete
  15. Hello Ben ,
    How can I config the pbx_connection_auth.xml file to make a connection by datamodule or modem ???
    Thanks

    ReplyDelete
  16. Hello Ben ,
    It is perfect , but I do not understand how to use it via modem , com/tty port or datamodule ?

    ReplyDelete
    Replies
    1. I haven't used data modules or modems in years, but the "atdt" attribute in the config file is for a dial string to send after connecting (telnet or ssh) to the address of a terminal server with your data modules/modems connected. I think we tried some single port adapters from Lantronix, and also had a Linux box setup as a terminal server for a while.

      Delete
  17. Hi Ben,
    I get this error when pressing "Submit"in the web interface and I don't know why or where it comes from.
    "Could not connect to pbxd server on ....: Permission denied"
    Do you have any ideas? It is built on CentOS 6.

    Thanks

    ReplyDelete
    Replies
    1. I've never seen that one, but my guess is that it's SELinux as described here http://stackoverflow.com/questions/17070031/perl-iosocketinet-permission-denied

      Delete
    2. Thank You! That made it work!

      Delete

Note: Only a member of this blog may post a comment.