5. Advanced Configuration

5.1. Remote TAPI Adapter Setup

Distributed first-party TSP support by means of remote TAPI Adapters has been introduced in release 1.3.0. Before proceeding, confirm:

  • You are running an appropriate software version.
  • Promptar TAPI Connector is not running.

 

Connector - Using remote Adapters

In its default configuration, Promptar TAPI Connector uses a local TAPI Adapter and establishes communications with it automatically.

When using remote TAPI Adapters, the connector must be configured to listen for remote TAPI Adapter connections on an available TCP port. To do that:

  • Select a TCP port to be used for such connections on your host.
  • Edit the connector configuration file on the server system by including the following two lines in the [tapi] section:
[tapi]

adapter.type      = remote
adapter.location  = <ip-v4-address>:<tcp-port>
  • <ip-v4-address> should be an IPv4 address: either 0.0.0.0 to listen on all available interfaces or the address of a particular interface in the system.
  • <tcp-port> should be the selected TCP port.

Firewall

 

Do not forget to adjust any local or remote firewall rules and networking equipment to support the incoming connections.

 

Client systems - Setting up

Execute these procedures on each client system that will be supporting a TSP:

step procedure

TSP installation and setup

Refer to your TSP’s documentation to complete this step.

TAPI Connector installation

Refer to the the Installation chapter.

List available local lines

Launch an administrative command line shell:

  • Run the prptTAPI -x listlines command on the client system, as described in the Configuration chapter.
  • Note that no configuration file is required on the client.
  • Do not proceed until the expected TAPI line is displayed locally.

Setup the TAPI Adapter service

Launch an administrative command line shell and change the working directory to the services sub-directory of the adapters plaftorm dependent directory. Then run adapter-service.bat install and enter the requested information:

 ...\adapters\service> adapter-service.bat install
 Promptar TAPI Adapter service installation
 ------------------------------------------
 TAPI Connector host: <host>
 TAPI Connector port: <port>
 Optional line key: <key>

Where:

  • <host> is the IPv4 address [a] for the server system hosting the connector.
  • <port> is the TCP port selected before.
  • <key> is optional; when defined, the adapter’s line names will be prefixed with:

    • The hostname of the system running the adapter, if set to {hostname}.
    • The first address of each line, if set to {address}.
    • The supplied <key> value, otherwise.

Optional line key prefixes

Line key prefixes are used to differentiate equally named lines across different systems like, for example, when a first-party TSP provides a common line name regardless of the underlying line, device, user or address. When in use, prefixed line names -- in the format <prefix>:<line-name> -- will be detected by the connector with prptTAPI -x listlines and should be used in its configuration.

Start the TAPI Adapter service

From the same command line shell as in the previous step, execute:

 > sc start prptT2A

Confirmin the TAPI Adapter is running by executing:

 > sc query prptT2A

It should output the prptT2A service status as RUNNING. An alternative way of doing that is confirming the following command outputs a single line containing prptTAPIAdapter.exe:

 > tasklist | find "prpt"

Test the remote TAPI Adapter

On the central system, hosting the Promptar TAPI Connector, lauch a command line shell and run the prptTAPI -x listlines command, as described in the Configuration chapter.

 

Confirm that the TAPI lines available on the client system, obtained before, are now displayed on the central system, including any prefix that may have been configured.

[a] Or IPv4 resolvable hostname.

One improvement that may be put in place is filtering the TAPI lines each TAPI Adapter provides to the centralized connector. This requires direct manipulation of the registry:

  • Stop the TAPI Adapter by running sc stop prptT2A in an administrative command line shell.
  • Open the registry editor by lauching regedit.exe.
  • Navigate to HKLM\SYSTEM\CurrentControlSet\services\prptT2A\Parameters:

    • You should find a REG_EXPAND_SZ value named AppParameters.
    • It is of the form -r <delay> <host>:<port> where <delay> defaults to 5 and <host>/<port> match the values entered when initially configuring the TAPI Adapter.
  • Add TAPI line filtering:

    • Prepend -f <string> to the existing AppParameters value; ensure at least one space separates it from the rest.
    • TAPI lines not containing <string> will be discarded by the TAPI Adapter.
    • The <string> matching is case-sensitive.
    • Multiple -f <string> arguments can be included. In such cases, the TAPI Adapter will only consider the TAPI lines whose names contain at least one the specified <string> values.
  • Once done editing, start the TAPI Adapter by running sc start prptT2A in an administrative command line shell.
  • Use the prptTAPI -x listlines on the central system to confirm the filtering.

Client systems - Cleaning up

To undo the client system setup described before, execute the following steps:

step procedure

Stop the remote TAPI Adapter

Launch an administrative command line shell and execute:

 > sc stop prptT2A

Confirm the TAPI Adapter is stopped by executing:

 > sc query prptT2A

It should output the prptT2A service status as STOPPED. An alternative way of doing that is confirming the following command outputs no lines:

 > tasklist | find "prpt"

Remove the TAPI Adapter service

Change the working directory to the services sub-directory of the adapters plaftorm dependent directory. Then run adapter-service.bat uninstall.

Uninstall the TAPI Connector

Use the native software removal tools to uninstall Promptar TAPI Connector.

The configuration and logs plaform dependent directories may still contain files after the procedure. You may keep them or delete them, depending on your systems management policy.

Uninstall TSP

Refer to your TSP’s documentation to complete this step.

5.2. PBX Features

Promptar TAPI Connector matches as many call control capabilities as the existing envirnoment supports: these are dictated by the installed TSPs and associated phone system.

In some cases, a particular feature may not be supported and end users will be faced with failures when triggering them; answering calls from Promptar, for example, is not supported by many TSPs. Thus, disabling such features is recommended. When disabled, the Promptar Desktop Client user interface disables the associated controls. This helps adjusting end user expectations, preventing frustration when trying trigger unsupported call control actions.

PBX features are controlled in the [pbx-features] section of the configuration file. By default, all features are enabled. To disable a particular feature a line should be added to this section, formatted like:

<feature> = no

The next table summarizes the controllable features:

featuredescription

call.init

Enables/disables call initiation from the Promptar Desktop Client: either by bringing up the control window on the bottom right side of the screen or via the integrated URL handler for click-to-call actions.

 

Uses TAPI’s lineMakeCall to initiate a phone call; lineSetupTransfer will be used instead if the line currenly has other calls.

call.answer

Enables/disables call answering support from the Promptar Desktop Client. When enabled, incoming calls display a green answer button in the bottom left of the associated call window.

 

Uses TAPI’s lineAnswer to answer an incoming call.

call.hold

Enables/disables call holding/resuming from the Promptar Desktop Client. When enabled, active calls display a hold/resume button in the bottom left of the associated call window.

 

Uses TAPI’s lineHold/lineUnhold to hold/resume a call.

call.redirect

Enables/disables blind call transfers from the Promptar Desktop Client. When enabled, the second button from the left in call windows can be used to transfer calls to another destination [a].

 

Uses TAPI’s lineBlindTransfer to perform the blind transfer.

call.join

Enables/disables support for assisted call transfers from the Promptar Desktop Client. When enabled and in the presense of at least two calls - one on hold, the other talking - the second button from the left in the held call window can be used to complete the transfer: it does that by joining the both parties in the calls, the talking one and the held one on which the button was clicked.

 

Uses TAPI’s lineCompleteTransfer to complete the assisted transfer.

[a] Not all TSPs support transferring a call in all states: some require calls to be answered first, others require them to be on hold, for example.

5.3. Fine Tuning

The remainder of this chapter goes through a few configurable options, describing their purpose and possible adjustments. Equivalent information is presented within the sample configuration file comments.

 

[server] section

There is a single configurable parameter here: timeout. It defines the amount of time, in seconds, the Promptar TAPI Connector waits for Promptar Server to acknowledge call event notifications.

In general, the default is more than adequate and Promptar TAPI Connector will log warnings if Promptar Server does not acknowledge call events within the timeout - this can be an indication of processing or network constraints that indicate potentially diminished user experience. Further diagnosing the underlying motives is recommended.

To completely disable such control, timeout can be set to 0, altough this is not recommended.

 

[tapi] section

Other than the parameters mentioned in the Remote TAPI Adapter Setup section above, there are a few other ones:

parameterdescription

adapter.keepalive

Defines how often, in seconds, Promptar TAPI Connector sends keep-alive messages to remote adapters.

 

This supports tracking lost-connections and is particularly relevant in scenarios where adapter connectivity is very dynamic. It defaults to 60 seconds and can be brought down for faster detection at the cost of additional network utilization. If set to 0, no keep-alive packets are sent to the adapters.

adapter.timeout

Defines how long, in seconds, Promptar TAPI Connector waits for adapter keep-alive responses.

 

Defaults to 5 seconds. If no response is received within this period, the connector will forcefully drop the adapter connection.

timeout

Defines the timeout, in seconds, that Promptar TAPI Connector uses while waiting for the confirmation of a given call control command sent to a TSP. If no such confirmation is obtained within the defined timeout, a warning message is logged and no further tracking is done on the command: it may fail or succeed.

 

The default is 1 second, a compromise between user experience control and slow TSPs. If timeout warnings are logged repeatedly, this can be an indication of a diminished user experience and diagnosing the underlying causes is recommended.

timeout.start

Defines the timeout, in seconds, that Promptar TAPI Connector uses in its initialization process. This comprises establishing communication with one or more TAPI Adpaters, initializing the associated TSPs, discovering available TAPI lines and initializing the ones configured to be used.

 

The prptTAPI -x listlines command times out after two times this value and, as mentioned in the Configuration chapter, in some cases, needs to be increased significatively to obtain successful startup results when dealing with particularly slow TSPs.

linename.match

Defaults to strict and can be set to regexp.

 

Defines how the connector matches the configured TAPI line names for the extensions (in the [extensions] section) against available TAPI line names. In the default configuration, strict requires the configured line names to exactly match the available ones and will fail otherwise. When set to regexp, the configured line names will be used as a regular expressions which are matched against the available line names. If multiple matches are found for a given configured regular expression, a warning will be issued and one of the available lines will be used: which one is selected is non deterministic and the recommended action is to adjust the configured line name regular expression such that it results in a single match.

 

The default setting should work in most circumstances. The more flexible setting has been put in place to handle TAPI stacks with dynamic line names.

event.match

Defaults to strict and can be set to loose.

 

Defines how the connector matches adapter events to configured extensions. In the default configuration, strict sets the connector to match strictly based on the configured extensions TAPI line names. When set to loose the connector starts by trying to match based on the TAPI line names and falls back to matching based on caller / called IDs if the line name based matching fails.

 

The default setting should work in most circumstances. The more flexible setting has been put in place to handle misbehaving TAPI stacks and to increase robustness if adapter failures show up.

call.ownership

Defaults to first-time and can be set to always.

 

Low level configuration setting that defines when TAPI call ownership should be requested. In the default configuration, first-time, the TAPI call ownership will be requested once, immediately after the connector/adapter is notified of a new call. When set to always, TAPI call ownership will be requested before every call control operation.