3. Minimal Configuration

The recommended first step in configuring Promptar Server focuses on the essentials and allows one to validate its basic operation. It consists of:

With this configuration the following critical aspects are validated:

3.1. Promptar Components

To move forward with a minimal Promptar Server installation, you will need to install:

  • The adequate Telephony Connector for your PBX system.
  • The Desktop Client Connector, DCC for short.
  • Promptar Desktop Client on a Windows or Mac system.

For that, please consult the respective setup guides.

3.2. Sample Configuration Files

The installation procedure for each Promptar software component, creates sample configuration files in the platform dependent configuration file directory. These files have a .conf.sample extension and contain, within themselves, multiple comments and examples. Please take your time having a look at those.

Copy each .conf.sample file to the respective .conf file. When completed, you should have the following files:

name purpose

general.conf

General configuration: logging, work directories, etc.

license.conf

Licensing Information. You will be provided the contents of this file.

plugins.conf

Connector configuration: which connectors the server will use.

users.conf

Users and Groups definitions.

integration.conf

Rules and templates the server will apply.

3.3. Editing Configuration Files

The Promptar Server configuration files are .INI like files and should be edited with a regular text editor. Since we’re starting off with the sample configuration files and they include 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.

 

general.conf

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

[log]

; Recommended configuration
; -------------------------
; type = file
; file = /var/log/promptar/prptServer.log
; file = C:/Program Files/Promptar Server/Log/prptServer.log
; file = C:/Program Files (x86)/Promptar Server/Log/prptServer.log
; file.rotate.when  = 1 midnight
; file.rotate.count = 7
; level = warning
; level.exprsEng = critical
; level.rules = error

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.

Continue by moving down to the [data] section and uncommenting the relevant location setting for your host:

[data]

; Recommended configuration
; -----------------------------------
; location = /var/lib/promptar/prptServer
; location = C:/Program Files/Promptar Server/data
; location = C:/Program Files (x86)/Promptar Server/data

Again, these settings can be changed. However, if you stick to these, you can rest assured the relevant directory has already been created for you during the installation process.

Move down to the [debug] section where you will find:

[debug]

shell           = true
interface       = 127.0.0.1
port            = 55000
username        = promptar
password        = qwepoi123098

The debug shell will be available over a TELNET interface on the given interface and port. Access is controlled by the username and password credentials defined here.

In general, it is recommended to:

  • Ensure the debug shell is active by having shell set to true. This is useful both in diagnosing a live running server and in validating/testing particular configurations as we will do later in this guide.
  • Keep the listening interface set to 127.0.0.1, so that no connectivity is allowed from outside the host.
  • Change the username and/or password.
  • Since the password is written in cleartext, if non-administrator users will ever log into this host’s operating system shell, change this file’s access permissions so that they can’t read it (unless, of course, you don’t mind those users having access to the Promptar Server’s debug shell).

 

license.conf

This file contains a single section, itself named [license]. It should contain the necessary licensing information as per your entitlement and will typically be delivered to you by your Promptar partner or by TMeA directly. Just replace the existing license.conf file with the one you received.

Please note that without a valid license.conf file the software will not run at all.

 

plugins.conf

This file defines not only which connectors Promptar Server will use but also how it should connect to each of them (it is named plugins.conf because, technically, connectors are particular cases of what the server considers plugins).

In this first configuration phase, we’ll keep things as simple as possible by just running the Telephony Connector and the Desktop Client Connector.

On editing the file you will find a [general] section defining a few timeouts. You can leave them with the default values and move down to the [plugins] section where you will find something like:

[plugins]

tel.name       = Telephony Connector
tel.type       = local
; tel.location = /opt/prptAMI/sbin/prptAMI
; tel.location = /opt/prptCSTA/sbin/prptCSTA
; tel.location = /opt/prptXLATE/sbin/prptXLATE
; 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
...

dcc.name       = Desktop Client Connector
dcc.type       = local
; dcc.location = /opt/prptDCC/sbin/prptDCC
; dcc.location = C:/Program Files/Promptar Desktop Client Connector/sbin/prptDCC.exe
; dcc.location = C:/Program Files (x86)/Promptar Desktop Client Connector/sbin/prptDCC.exe
; dcc.type     = remote
; dcc.location = 127.0.0.1:10000
dcc.trust      = yes

...

The section itself continues with several commented our sample definitions for other connectors. Proceed by uncommenting the appropriate tel.location and dcc.location lines for your environment. These define the absolute path to the respective connector executable and will be used by Promptar Server to start off the connectors during its initialization process.

 

users.conf

This file contains the definitions for Users and Groups within Promptar Server. Things you want to know:

  • At least one Group must be defined.
  • Users and Groups have IDs and Names.
  • Users are associated to a single Group.
  • Users login with their respective ID and password.
  • The password is stored as a salted hash in this file. The Server binary can be used to generate/validate them.

To keep things as simple as possible at this stage, fill-out the following table for each of the two to three initial test users:

user ID user name user password user extension

 

 

 

 

 

 

 

 

  • User IDs are sequences of letters/digits that must begin with a letter and contain no whitespace; they can also include characters such as "." (dot), "_" (underscore) and "-" (dash).
  • User Names are typically "First Name Last Name" character strings where not only spaces can be used but also non-ASCII characters [1].
  • User Passwords are stored in salted hash format in this file. See the note below, Generating Password Hashes.
  • User Extensions should be PBX extension addresses associated to each user. These will probably be sequences of digits and will need to be be configured within the Telephony Connector scope.

 

Generating Password Hashes

 

Generating password hashes is acheived by running the server binary from a command shell.

In a Linux environment, for example, run:

# cd /opt/prptServer/sbin
# ./prptServer pass.hash secret
daf33f217e0d0de95762aa32120e71c06a71a20abbae5426

 

In a 64 bit Windows environment, run instead:

> cd \Program Files (x86)\Promptar Server\sbin
> prptServer.exe pass.hash secret
cbaafdd5275edae480bfe147dc2de7bb7bdc67fd2af152a6

 

A random salt is generated on each run, so you should expect different results when hashing the same password multiple times ("secret" in the examples).

 

At the top you will find the [general] section where both the default group and the user session timeout are defined:

[general]

default-group   = users
session-timeout = 300

Leave these defaults as provided and proceed downwards to the [groups] section, where you will find the default group’s declaration (Group ID is users):

[groups]

users.name              = Promptar Users

For now these declarations are sufficient, so scroll down to the [users] section. This is where you will want to add your user entries:

[users]

As in most cases, you will find multiple examples in the preceeding comments.

Add user declarations after [users] section line. For each user you should add four lines formatted like [2]:

<user-id>.name        = <user-name>
<user-id>.password    = <salted-password-hash>
                      # password is <password>
<user-id>.exten       = <user-extension>

NOTE: In previous software releases, the user/extension relationship was defined in the integration.conf file, in a section called [user-extensions]. Such configurations are still supported, for backwards compatibility, but updating the configuration is recommended.

 

integration.conf

This is the file where you will spend most time customizing Promptar Server’s behavior. It’s definitions comprise:

  • Declaration of static, server based data items.
  • Defining, on a per Group basis, where contact lookups should be performed.
  • Defining sets of Templates and Rules that establish what type of information should be collected and delivered to the users for any given call.

Proceed to opening integration.conf with your text editor. Near the top you will find the [data] section, where server data items are declared. For now, skip it and scroll down to the [defaults] section. This holds two types of definitions: one defines how Promptar Server gets data from Application Connectors, something we do not need yet; the other defines, either on a global or on a per user group basis, where contact lookups should be performed. At the current stage we will stick to the simplest possible configuration: setting up the server such that all users requested contact lookups are directed at its internal user list. This is the default:

[defaults]

lookup  = server

The next section, [templates] [3], is where the Templates are defined. For now, no changes should be necessary. Just confirm that both the users and internal templates are defined and uncommented. These represent the information to be collected and delivered to each Promptar user when the peer [4] is either i) also a Promptar user or ii) someone from within the organization; in other words, these templates focus on internal calls.

Here is a quick rundown through them:

[templates]

users.name                  = User on the phone with a Promptar User
users.field.h1.value        = {peerUser.name}
users.field.h2.value        = {peerGroup.name}

internal.name               = Internal Calls - Peer is not a Promptar User
internal.field.h1.value     = "Extension " + {call.peerAddress}
internal.field.h2.value     = "Internal Call"

Again, for now, keep them unchanged and proceed downwards to the [rules] [5] section. Here you should find, as mostly everywhere, both comments and examples which we will keep unchanged.

At the top of the section you should find two active Rules:

[rules]

users.name              = Internal Calls: between Promptar users
users.condition         = {peerUser.id|""} != ""
users.template          = users

internal.name           = Internal Calls: Promptar user to/from non-user
internal.condition      = len({call.peerAddress|""}) <= {server.data.ext_len}
internal.template       = internal

The first one, with an ID of users, will activate the template with the same ID, if the peer is a Promptar user. The second one, which will only be evaluated if the first one is false, activates the internal template if the peer’s address (in other words, the peer’s caller ID or extension number) has {server.data.ext_len} digits or less.

The {server.data.ext_len} data item defaults to 4 and is declared at the top of the file, in the [data] section. You may want to change its value and/or adapt the rule’s internal.condition expression: by default it considers that a phone number with 4 digits or less is an internal extension and, thusly, activates the internal template.

This wraps up the initial Promptar Server configuration.

3.4. Connectors

Before proceeding to the initial tests, you need to ensure the configuration of:

  • The Telephony Connector.
  • The Desktop Client Connector.

For that, please refer to the respective setup guides.

 

 

3.5. Start/Stop OS Integration

As a last step before proceeding to the initial tests, it is recommended that Promptar Server’s startup and shutdown procedures are integrated with the operating system services.

 

Linux

Under the Scripts directory, a RHEL5 compatible Sys V init file is provided. To perform the integration, change the working directory there and execute:

# cp prptServer.init-rhel5 /etc/init.d/prptServer
# chkconfig --add prptServer

From here on, Promptar Server can be managed to start or stop just like any standard system service under the name prptServer and will do so along with the host operating system.

If you ever want to revert this process, execute:

# chkconfig --del prptServer
# rm /etc/init.d/prptServer

 

Windows

Under the service directory, a few helper files support this process. To perform the integration, change the working directory there and execute:

C:\Program Files (x86)\Promptar Server\service> service-install.bat

From here on, Promptar Server can be managed to start or stop just like any standard system service under the name prptServer and will do so along with the host operating system.

To undo such integration, run the service-uninstall.bat script under the same directory.



[1] for that, ensure the encoding of the text file is UTF-8 with no BOM

[2] Depending on the password policies you want to implement, it may be a good idea to keep the clear text password in a commented line in the file, as suggested. As we’ll see later on, this may help us reset the user password to its original value should a particular user ever forget what he/she changed the password to

[3] In previous software releases this section used to be called dataset-templates. Such naming is still accepted for backwards compatibility reasons, but updating it is recommended.

[4] In Promptar terms, the peer represents the party on the other side of each phone call, from the perspective of the Promptar User. Whether the call was initiated by the user towards the peer or the other way around.

[5] In previous software releases this section used to be called dataset-conditions. Such naming is still accepted for backwards compatibility reasons, but updating it is recommended.