5. Detailed Configuration

5.1. HTTP Servers

Promptar HTTPBX connector can run one or more HTTP servers simultaneously. For each such server, a block of <server-id>.<option> settings should be added to the [http] section of the configuration file.

Refer to the following table for the possible configuration options:

option description

protocol

One of http or https. When using https, the key and cert options are required.

interface

The IPv4 address where the server listens for requests. Defaults to all existing interfaces.

port

The TCP port where the server listens for requests. Defaults to 80 if protocol is http and to 443 if protocol is https.

fallback

Set to yes to handle and log requests not passed to associated drivers, that would otherwise return a 404. Useful for diagnostics. Defaults to no.

auth

One of basic or digest. If set, the username and password options are required and HTTP authentication is performed on incoming requests. No authentication is used if undefined.

username

See auth, above.

password

See auth, above.

key

The HTTPS server private key. The path, relative to the configuration file, of a PEM encoded private key file.

cert

The HTTPS server certificate. The path, relative to the configuration file, of a PEM encoded certificate file.

trust

The HTTPS server trusted Certificate Authority list. The path, relative to the configuration file, of a file containing one of more CA certificates, against which the server validates client certificates [a]. No client certificate validation is performed if undefined.

[a] The connector ships with two such files, polycom.ca-bundle.sample and snom.ca-bundle.sample, allowing the validation of requests from those manufacturer’s phones.

5.2. Common Driver Options

With the exception of the Broadworks driver, all remainining ones share a common set of configuration options.

Refer to the following table for those options, to be used as <driver>.<option> under the [drivers] section of the configuration file:

option description

server.id

Identifies the server under which the driver should be exposed. Must match a server declated in the [http] section.

server.path

The path under which the driver should be exposed. Defaults to /<driver>/ and normally does not need adjustment.

client.protocol

One of http or https. Defines the protocol for the driver to use when sending HTTP requests.

client.port

Defines the TCP port for the driver to use when sending HTTP requests. Defaults to 80 if client.protocol is http, and to 443 if https.

client.ca

The path of a file containing a list of PEM encoded CA certificates. Only used when client.protocol is https. When set, the driver will validate the phone system certificate(s) against it. No validation is performed if undefined.

client.auth

One of basic or digest. Default HTTP authentication mechanism to use when sending HTTP requests. No authentication is attempted by default if undefined.

client.username

Used for authenticating outgoint HTTP requests. Normally overridden by an equivalent setting on a per-extension basis.

client.password

Used for authenticating outgoint HTTP requests. Normally overridden by an equivalent setting on a per-extension basis.

5.3. Broadworks

The Broadworks driver is implemented per XSI release 21.0. In its current implementation, an independent Event Channel is used for each configured extension.

Refer to the following table for available driver configuration options, to be used as broadworks.client.<option> under the [drivers] section of the configuration file:

option description

url

Broadworks XSI URL of the system to be used.

max-redir

Maximum HTTP redirections to allow. Defaults to 3.

hb-secs

Heartbeat period, in secods. Defaults to 15.

ec-req-secs

Event Channel request period, in seconds. Defaults to 3600.

ec-upd-when

When, as a percentage of the time period ec-req-secs, should the Event Channel be updated. Defaults to 50%.

ec-reconnect

One of yes or no defines whether the driver should reconnect if the Event Channel is disconnected. Defaults to yes.

ec-rcnt-secs

Delay before reconnecting the Event Channel, in seconds. Defaults to 5.

ec-rcnt-jttr

Jitter to apply to ec-rcnt-secs, as a percentage of itself. Defaults to 50%.

ec-rcnt-mult

Multiplier for ec-rcnt-secs in subsequent Event Channel reconnect attempts. Defaults to 1.2.

ec-rcnt-smax

Maximum Event Channel reconnect delay, in seconds. Defaults to 3600.

sub-req-secs

Subscription request period, in seconds. Defaults to 3600.

sub-upd-when

When, as a percentage of the time period sub-req-secs, should the subscription be renewed. Defaults to 50%.

version

Allows requesting a specific version of the XSI spec. No default value. Use to force a particular XSI version when setting up a particular environment. This driver should work, at least, with versions 19.0 and later.

Regarding extensions, there are no additional details, other than what’s described in the previous chapter.

5.4. Switchvox

Refer to the following table for all available driver configuration options, to be used as switchvox.<option> under the [drivers] section of the configuration file:

option description

client.url

The XML API URL of the Switchvox system.

handle.send-to-vm

One of ignore, terminate or update-address. Defines how the connector signals calls directed at a configured extension when they are redirected to voicemail. If set to terminate, the connector signals call termination towards the server; if set to update-address, the connector updates the destination address by appending handle.stv-suffix to it [a]. The default is ignore which results in the call termination being signalled only once the redirected to voicemail caller hangs up.

handle.stv-suffix

Defaults to the string -vm and is used when handle.send-to-vm is set to update-address.

[a] From a receiving user perspective the call seems to end, but the server can still track it.

Regarding extensions, there are no additional details, other than what’s described in the previous chapter.

5.5. Polycom Phones

The Polycom driver performs call control commands via push requests towards individual phones. Each of those requests acts as if a given key or key sequence was physically pressed on the phone device itself.

Given the dynamic and configurable nature of the phone soft-keys, used for some call manipulation actions, the driver allows for the configuration of which key commands to send for a given desired call action. Such commands are defined as one or more internal URIs [12] and can be configured driver-wide or on a per-extension basis.

About phone models

 

Given the diversity of phone models and software/firmware versions, the driver defaults for call control will probably not match your environment. They are set for VVX 200 series phones running UCS 5.5 and may need adjustment for correct operation when using other models or software/firmware versions.

Refer to the following table for available driver configuration options, to be used as polycom.handle.<option> under the [drivers] section of the configuration file:

option description

control

One of strict or loose. In the presence of multiple calls, some operations, like call answering or performing a blind transfer, are likely to fail, given that call control is performed by issuing key presses and that the device and soft-key states can vary a lot.

To ensure that no call control actions with possibly unexpected results are issued, the driver defaults to operate in strict mode where, for example, call answering or blind-transfering commands are not sent to the phone unless there is a single call in the correct state.

When set to loose the driver imposes no limitations on sending call control requests to the phones.

cc-init

URIs used to initiate a call. Must include the %s placeholder which will be replaced by the destination number. Defaults to Tel:%s.

cc-answer

URIs used to answer an incoming a call. Defaults to Key:Handsfree.

cc-hold

URIs used to hold an active call. Defaults to Key:Hold.

cc-resume

URIs used to resume a held call. Defaults to Key:Hold.

cc-hangup-ring

URIs used to hangup an incoming ringing call. Defaults to Key:Softkey2, Reject on VVX 200 series phones.

cc-hangup-talk

URIs used to hangup an active call. Defaults to Key:Softkey2, End on VVX 200 series phones.

cc-hangup-hold

URIs used to hangup a held call. Defaults to Key:Hold Key:Softkey2 that first resumes the call and then hangs it up.

cc-redir-ring

URIs used to blind-transfer an incoming ringing call. Must include the %s placeholder which will be replaced by the destination number. Defaults to Key:Softkey3 %s Key:Softkey3

cc-redir-talk

URIs used to blind-transfer an active call. Must include the %s placeholder which will be replaced by the destination number. Defaults to Key:Softkey3 %s Key:Softkey1 Key:Softkey3.

cc-redir-hold

URIs used to blind-transfer a held call. Must include the %s placeholder which will be replaced by the destination number. Defaults to Key:Softkey3 %s Key:Softkey1 Key:Softkey3.

cc-join

URIs used to complete an attended transfer between an active call and a held call. Defaults to Key:Softkey4 Key:Softkey2 Key:Softkey2.

Regarding extensions, other than what’s described in the previous chapter, the driver supports setting the above described call control configuration settings on a per extension basis. For that, use the same options under the <extension>.<option> settings for each individual extension.

For completeness, here is an example of a fully customised extension configuration:

[extensions]

401.identity       = polycom/sip:401@your.pbx.fqdn/64167f8433a4:1
401.auth           = basic:pushuser:pushpass
401.cc-init        = Tel:%s
401.cc-answer      = Key:Handsfree
401.cc-hold        = Key:Hold
401.cc-resume      = Key:Hold
401.cc-hangup-ring = Key:Softkey2
401.cc-hangup-talk = Key:Softkey2
401.cc-hangup-hold = Key:Hold Key:Softkey2
401.cc-redir-ring  = Key:Softkey3 %s Key:Softkey3
401.cc-redir-talk  = Key:Softkey3 %s Key:Softkey1 Key:Softkey3
401.cc-redir-hold  = Key:Softkey3 %s Key:Softkey1 Key:Softkey3
401.cc-join        = Key:Softkey4 Key:Softkey2 Key:Softkey2

5.6. Snom Phones

The Snom driver performs call control commands via HTTP requests towards individual phones. Each of those requests acts as if a given key or key sequence was physically pressed on the phone device itself.

Refer to the following table for available driver configuration options, to be used as snom.handle.<option> under the [drivers] section of the configuration file:

option description

identity

One of full-uri or user-only. Defaults to full-uri. When set to user-only, Snom extension identity options in the [extensions] section may be shortened to the user part of the SIP URI (ie: snom/402 instead of snom/402@your.pbx.fqdn).

control

One of strict or loose. In the presence of multiple calls, some operations, like call answering or performing a blind transfer, are likely to fail, given that call control is performed by issuing key presses and that the device and soft-key states can vary a lot.

To ensure that no call control actions with possibly unexpected results are issued, the driver defaults to operate in strict mode where, for example, call answering or blind-transfering commands are not sent to the phone unless there is a single call in the correct state.

When set to loose the driver imposes no limitations on sending call control requests to the phones.

Regarding extensions, other than what’s described in the previous chapter and what relates to the above mentioned snom.handle.identity option, there are no additional details.

5.7. Yealink Phones

The Yealink driver performs call control commands via HTTP requests towards individual phones. Each of those requests acts as if a given key or key sequence was physically pressed on the phone device itself.

Refer to the following table for available driver configuration options, to be used as yealink.handle.<option> under the [drivers] section of the configuration file:

option description

control

One of strict or loose. In the presence of multiple calls, some operations, like call answering or performing a blind transfer, are likely to fail, given that call control is performed by issuing key presses and that the device and soft-key states can vary a lot.

To ensure that no call control actions with possibly unexpected results are issued, the driver defaults to operate in strict mode where, for example, call answering or blind-transfering commands are not sent to the phone unless there is a single call in the correct state.

When set to loose the driver imposes no limitations on sending call control requests to the phones.

Regarding extensions, other than what’s described in the previous chapter, there are no additional details.



[12] Handled by the devices themselves and documented in the Web Application for Polycom Phones Developer Guide.