4. Configuration

4.1. Planning

Configuring XLATE requires some planning ahead, like most things in a Promptar setup. With the concepts described in the first chapter in mind, identifying the phone number formats across the solution is fundamental.

To do that, a minimal, single user, Promptar installation with the server, DCC and the phone system connector is enough; more complex solutions will work as well. Two sets of phone number formats should be identified:

  • Phone number formats produced by the phone system, included in the phone system connector call notifications.
  • Phone number formats supported by the phone system to initiate calls on behalf of the users.

The following lists include sets of tests to indentify phone number formats that may be relevant for a given solution. For each test, the desktop client call window should be used to note the other party’s phone number format[6]:

  • Calls towards the user extension:

    • Initiated from the phone device of another internal extension.
    • Initiated by an external, national caller, in the local area.
    • Initiated by an external, national caller, not in the local area.
    • Initiated by an external, national caller, on a mobile phone.
    • Initiated by an external, international caller.
  • Calls initiated by using the phone device associated to the user extension:

    • Towards another internal extension.
    • Towards an external, national party, in the local area.
    • Towards an external, national party, not in the local area.
    • Towards an external, national party, on a mobile phone.
    • Towards an external, international party.

Regarding desktop triggered call initiation, a similar set of tests should be run where calls should be initiated from the desktop instead of using the physical phone device. This will help understand which prefixes, if any, need to be added to reach specific destinations and, at the same time, whether these call initiation requests result in call notifications with slightly different phone number formats than the ones observed in the previous tests.

 

With this set of tests completed, half of the planning work is completed. The other half is related to how phone numbers are stored at the application level and how to facilitate actions such as Promptar record matching and user experience which, in itself, at the application level, will vary greatly from case to case.

Once complete, substitution rules to handle all the functional requirements should be created.

4.2. Sample Configuration File

The installation procedure for each Promptar software component, creates one sample configuration file in the platform dependent configuration file directory: it is named prptXLATE.conf.sample and contains, within itself, multiple comments and examples. Please take your time having a look at it.

Start by copying the prptXLATE.conf.sample to prptXLATE.conf.

4.3. Editing the Configuration File

The configuration file is a .INI like file and should be edited with a regular text editor. Since we’re starting off with the sample configuration and it includes several pre-defined, commented out settings, the majority of the initial work will be going through them uncommenting the appropriate ones for the given environment.

 

prptXLATE.conf

Open the prptXLATE.conf file and scroll down to the [log] section. You should find the following:

[log]

; Recommended configuration
; -------------------------
; type = file
; file = /var/log/promptar/prptXLATE.log
; file = C:/Program Files/Promptar Telephony Translation Plugin/Log/prptXLATE.log
; file = C:/Program Files (x86)/Promptar Telephony Translation Plugin/Log/prptXLATE.log
; file.rotate.when  = 1 midnight
; file.rotate.count = 7
; level = warning

Uncomment the lines starting with type, file and level, depending on whether you’re on a Linux or Windows host; pay particular attention the the line starting with file, pointing to the path of the log file. The recommended configuration ensures daily log file rotation while keeping 7 days worth of history. If you want to change these settings, please check the comments preceding these lines in the sample configuration file.

Skip the optional [network] section, and scroll down to the [connector] section where you should find:

; Sample local Linux based connector
; ----------------------------------
; type     = local
; location = /opt/prptAMI/sbin/prptAMI
; location = /opt/prptCSTA/sbin/prptCSTA
; location = /opt/prptHTTPBX/sbin/prptHTTPBX

; Sample local Windows based connector
; ------------------------------------
; type     = local
; location = C:/Program Files/Promptar AMI Connector/sbin/prptAMI.exe
; location = C:/Program Files/Promptar CSTA Connector/sbin/prptCSTA.exe
; location = C:/Program Files/Promptar TAPI Connector/sbin/prptTAPI.exe
; location = C:/Program Files/Promptar HTTPBX Connector/sbin/prptHTTPBX.exe
; location = C:/Program Files (x86)/Promptar AMI Connector/sbin/prptAMI.exe
; location = C:/Program Files (x86)/Promptar CSTA Connector/sbin/prptCSTA.exe
; location = C:/Program Files (x86)/Promptar TAPI Connector/sbin/prptTAPI.exe
; location = C:/Program Files (x86)/Promptar HTTPBX Connector/sbin/prptHTTPBX.exe

Given that XLATE will assume the phone system connector’s role from the perspective of Promptar Server, this section tells XLATE which actual phone system connector it should start or connect to, depending on its type: XLATE starts connectors with type set to local or connects to connectors with type set to remote [7].

Proceed by uncommenting the appropriate line for the environment and, if unsure, refer to the server’s plugins.conf file, under the [plugins] section, which is in many regards similar to this one.

Once done, save the configuration file and proceed to adjusting Promptar Server’s configuration to use XLATE as its phone system connector.

4.4. Server Reconfiguration

To reconfigure Promptar Server to use XLATE as its phone system connector edit the server’s plugins.conf configuration file and locate the entry pointing to the phone system connector in use.

Depending on the platform and environment, it will probably be one of:

tel.location = /opt/prptAMI/sbin/prptAMI
tel.location = /opt/prptCSTA/sbin/prptCSTA
tel.location = /opt/prptHTTPBX/sbin/prptHTTPBX
tel.location = C:/Program Files/Promptar AMI Connector/sbin/prptAMI.exe
tel.location = C:/Program Files/Promptar CSTA Connector/sbin/prptCSTA.exe
tel.location = C:/Program Files/Promptar TAPI Connector/sbin/prptTAPI.exe
tel.location = C:/Program Files/Promptar HTTPBX Connector/sbin/prptTAPI.exe
tel.location = C:/Program Files (x86)/Promptar AMI Connector/sbin/prptAMI.exe
tel.location = C:/Program Files (x86)/Promptar CSTA Connector/sbin/prptCSTA.exe
tel.location = C:/Program Files (x86)/Promptar TAPI Connector/sbin/prptTAPI.exe
tel.location = C:/Program Files (x86)/Promptar HTTPBX Connector/sbin/prptTAPI.exe

Comment it out with a leading ; or #, and replace it with an non-commented, similarly formatted entry pointing to XLATE; recent server versions include commented entries ready for this use case. Again, depending on the platform, use:

platform XLATE binary path

Linux

/opt/prptXLATE/sbin/prptXLATE

Windows

<prefix>[a]\Promptar Telephony Translation Plugin\sbin\prptXLATE.exe

[a] Where <prefix> is given by the Windows ProgramFiles environment variable on 32 bit systems, often set to C:\Program Files\; on 64 bit systems, it is given by the ProgramFiles(x86) environment variable, commonly set to C:\Program Files (x86)\.

Once done, (re)start Promptar Server and confirm that the phone system connector chain is brought up correctly: the server, XLATE and the phone system connector should all be running. If not, the following log files should be inspected, in order, to help determine why:

  • Promptar Server log.
  • XLATE’s log.
  • Phone system connector log.

This concludes the minimal possible configration, with XLATE sitting between Promptar Server and the phone system connector, doing no translations at all.

4.5. Rule Configuration

The last step in setting up XLATE is configuring the translation rules. These are defined in two independent pipelines, composed of three processing stages each, across the following configuration file sections:

  • [rules-server2telephony-clean]
  • [rules-server2telephony-normalize]
  • [rules-server2telephony-map]

And:

  • [rules-telephony2server-clean]
  • [rules-telephony2server-normalize]
  • [rules-telephony2server-map]

Each of these sections may hold zero, one or more translation rules formatted as below, where <matching-re> is a regular expression and <replacement-re> is a replacement expression, optionally referencing capture groups in <matching-re>:

<matching-re> = <replacement-re>

Refer to the XLATE Operation section in the first chapter for more details.

 

Recommended Procedure

The sample configuration file includes several commented out rules and associated notes. They reflect translation rules usable in common scenarios, including cleaning up user submitted phone numbers, normalization and prefix adding/removal.

  • Inspect the sample rules, uncomment them and adjust as needed.
  • Use the command line -x option to manually test your configuration:

    • Run prptXLATE -x s2t:<number> to test the server to phone system connector translation.
    • Run prptXLATE -x t2s:<number> to test the phone system connector to server translation.
  • Optionally set the logging level in the [log] section to debug to diagnose translations on a stage by stage basis.
  • Once completed, restart Promptar Server to apply the configured XLATE rules.

General Guidance

  • Other than in the cleanup rules, strive to start <matching-re> with ^, ending them with $.
  • Remember to escape the + symbol with \ when matching a literal +.
  • Keep the number of capture groups in <matching-re> small: often one is enough.
  • Change and test one rule at a time.
  • Once done, test all possible translations in both directions.



[6] The desktop client’s call window (i) button can be used to reveal the underlying phone number when a template is being displayed.

[7] For details on local vs. remote connectors and passing command line arguments to local ones, refer to the server documentation and the sample configuration files for both XLATE and the server.