Introduction

As customers purchase numbers, the stock of free numbers in inbound groups can decrease to an unacceptable level. At this point the system owner can order more, but an automated ordering system can prevent this from happening in the first place. This is done by defining the following for the inbound group:

  1. A minimum pool of free numbers.
  2. A mapping of which number vendors' groups match this inbound group.

Enswitch supports two modes for using these:

  • Pool: This is the recommended mode for performance reasons. After a number is used, the system checks if the number of free numbers in the inbound group is at least the minimum pool size. If not, sufficient numbers are ordered to bring the pool up to the minimum.
  • Real time: This mode should only be used if you have first verified that all your number vendors respond fast enough to make the Enswitch web interface responsive to users. The pool of free numbers can be below the minimum, and the system will make no attempt to fill the pool. However, when a customer requests a list of free numbers in the inbound group (so they can choose one to purchase), the system will ask the vendor(s) for enough numbers to show either 10 numbers or the minimum pool size, whichever is less. If the customer then purchases one of the vendors' numbers, the system will order this number from the vendor.

There are many number vendors available, and each has their own specific API. Therefore Enswitch uses external plugins to interface to these APIs. Which plugin to use depends on the number vendor's API:

Enswitch servers

If the vendor is running Enswitch 3.5 or later, or 3.4 with fixes later than 2011-02-28, you can use the plugin that is shipped with Enswitch in /opt/enswitch/current/sbin/numbervendors/enswitch. This plugin will always request numbers from the vendor in E.164 format. The API on the server side will convert the vendor's numbers to E.164, and this plugin will convert the numbers received to your system dial plan. As long as both systems have their system dial plans set correctly under Global » Settings » Configuration you therefore don't need to worry about differences in dial plan. A suggested sample configuration line is: 

# Vendor = Name, Method, Host, User, Password, Destination
testvendor = Test Vendor, /opt/enswitch/current/sbin/numbervendors/enswitch, api.testvendor.com, testuser, testpassword, sip.myenswitch.com:5060

For more details, see the configuration section below.

Voxbone

You an use the plugin that is shipped with Enswitch in /opt/enswitch/current/sbin/numbervendors/voxbone. This plugin hard codes the host to connect to so this is not required in configuration. A suggested sample configuration line is: 

# Vendor = Name, Method, Host, User, Password, Destination
voxbone = Voxbone, /opt/enswitch/current/sbin/numbervendors/voxbone, ,testuser, testpassword, sip.myenswitch.com:5060

For more details, see the configuration section below.

Other servers

If the vendor uses a different API, you will need to write a plugin to interface to their API. Plugins are invoked from Enswitch using system(), and so can be written in any programming language.

Input parameters

Enswitch will pass the following parameters to the plugin:

  • -v: The name of the vendor as used in the Enswitch database.
  • -n: The human-readable name of the Vendor.
  • -h: The host to connect to. For some vendors this not be passed, in which case the plugin is expected to hard-code the host.
  • -u: The username for the number vendor.
  • -p: The password for the number vendor.
  • -a: The action. See below for more details.
  • -g: The group to order or list numbers from.
  • -d: The destination address to send the number to. Typically a hostname or IP address, optionally followed by colon and a port. Only passed on the add_numbers_from_group action.
  • -c: The quantity (count) of numbers to order or list. If not set, the plugin should assume 1.
  • -o: A particular number to order. If this number is unavailable, the plugin should return an error. If used with -c, the remaining numbers may be chosen freely by the plugin. Only passed on the add_numbers_from_group action.

For example:

testvendorplugin -v testvendor -n 'Test Vendor' -h api.testvendor.com -u testuser -p testpassword -a add_numbers_from_group -g 123 -d sip.myenswitch.com:5060 -c 1 -o 2125551212

Output format

The plugin is expected to return data on STDOUT. The first line should be either "OK\n" if the action was successful, or "ERROR\n" if it was not. OK and ERROR may be optionally followed by a space then a further message. Enswitch will not use this further message; it is for your testing use only. Examples of errors are:

ERROR
ERROR Username or password incorrect

The second lines onwards return the useful data. See the actions section below for details. Each line in the output must be terminated by a newline character.

The get_groups action

This action requests a list of all the number groups from the vendor. This allows the Enswitch system administrator to choose which of the vendor's groups correspond to the inbound group they are configuring. The plugin shall return data in the following format:

OK
id1, Group 1
id2, Group 2

The first column is the group ID as specified by the vendor. It can be letters and/or numbers. It must not change as Enswitch will store it in the Enswitch database. The second column is the human readable name of the group, which may change if needed.

If no groups can be found, an error must be returned.

The add_numbers_from_group action

This action requests that the plugin order a number or numbers (set by -c) from the vendor and set the number(s) to forward to Enswitch. The vendor's group ID will be passed in the -g parameter, and the host part of the destination passed in the -d parameter. The plugin may need to build a SIP URI based on the number and destination. The plugin should return the number(s) as seen by Enswitch customers (which may be a different format to how the vendor presents it).

For example, if the Enswitch system is in the UK and has Kamailio service address sip.myenswitch.com, and the vendor returns 442071234567 (E.164 format), the plugin should map 442071234567 to 02071234567, tell the vendor to send the number to sip:02071234567@sip.myenswitch.com, and print: 

OK
02071234567

If the plugin returns an error, Enswitch will move on to the next number vendor group configured for the inbound group.

The get_available_numbers_from_group action

This actions gets a list of numbers from the vendor which are available to order. Enswitch will then present these numbers to the customer to purchase. The quantity of numbers to get is passed in the -c parameter, and the group to use is passed in the -g parameter. This action is only used if real time mode is in use. The output format is:

OK
02071234567
02079876543

If the plugin returns an error, Enswitch will move on to the next number vendor group configured for the inbound group.

Comments for developers

Some further comments of interest to developers:

  • An example Perl skeleton plugin can be found in /opt/enswitch/current/sbin/numbervendors/dummy.
  • A suggested place to save plugins is /usr/local/enswitch/numbervendors/<vendor>. You may need to make this directory.
  • Plugins must not be saved under /opt/enswitch. Any that are may be wiped out by Enswitch upgrades. In particular, /opt/enswitch/current/sbin/numbervendors is only for plugins that are shipped with Enswitch.
  • The plugin and configuration should be installed on all machines in the cluster running the web server.
  • The plugin must be executable by the "enswitch" user.
  • It's a good idea to prevent the plugin from running for an excessive time by using the alarm() system call. The plugins shipped with Enswitch run for a maximum of 50 seconds.

Configuration

To configure which number vendor plugins are used, first set "Enable number vendors" to "pool" or "realtime" under Global » Settings » Configuration. Then create /etc/enswitch/numbervendors.conf with the following format:

# Vendor = Name, Method, Host, User, Password, Destination
test = Test, /opt/enswitch/current/sbin/numbervendors/dummy, api.testvendor.com, testuser, testpassword, sip.myenswitch.com:5060

with one vendor per line. All fields must be specified, without spaces, but may be ignored by a plugin. The same plugin may be used on more than one line, for example if two vendors use the same API but at different hostnames. Any line starting # is considered a comment. Finally, restart the web server to make these changes take effect.

Copyright © Integrics Ltd., all rights reserved. Permission is granted for Enswitch partners, customers, and their resellers to copy the contents of this page into their own documentation and redistribute this to their customers.