Configuring Interaction Server DAP

This page explains how to configure Interaction Server to use ODBC database connections.

Important

Support for DB Server is dropped and existing environments must migrate to using ODBC connections.

Installing ODBC drivers

Important

As Interaction Server is a 64-bit application, the ODBC driver must support 64-bit architecture.
Installation of ODBC drivers might require administrator-level account privileges.
Interaction Server does not support alternative ODBC drivers and tools from third-party brands, unless they are explicitly listed in this document.

You must ensure that ODBC drivers are installed on each Interaction Server machine in your environment (primary and backup). Genesys recommends using the most recent driver release available for the respective database engine.

For Microsoft SQL Server, see one of the following pages for more information: Windows or Linux.
For Oracle, see one of the following pages for more information: Windows or Linux.
For PostgreSQL, see one of the following pages for more information: Windows or Linux.

It is recommended to configure the Data Source Name (DSN) for the hosts on which Interaction Server will run (see the DSN article in Wikipedia for more information). Follow the vendor instructions to install the ODBC driver and configure the DSN. Verify a successful connection to database with the tools that accompany the driver.

Preparing DAP configuration objects

New environment

For a new environment, create a Database Access Point (DAP) object as described in the Framework Database Connectivity Reference Guide and add the DAP to the connections of your Interaction Server.

To configure the database-oriented Event Logger for Interaction Server, create a second DAP object as described on the Deploying Event Logger page.

Existing environment

For an existing environment with Interaction Server 8.5.1 - 8.5.3 and DB Server, you should configure them to use ODBC to connect to database before the upgrade to version 9.0.0. Use Genesys Administration Extension (GAX) to create copies of the existing DAP objects used by Interaction Server. You can use these copies to switch back to connecting via DB Server while testing.

Configure the DAP

This section applies to Interaction Server and Event Logger. Related information about Database Capture Point is in a separate location.

For an ODBC connection, you must configure the Database Access Point (DAP) associated with the Application in question, as follows:

For Database Info configuration, in Genesys Administrator, enter the following in the [DB Info] section of the Configuration tab (in Configuration Manager, on the DB Info tab):
- DBMS Name - host name of the database server
- DBMS Type - type of the database
- Database Name - name of the database
- User Name - user name to use to connect to the database
- Password - password for the user name account
Configure the options of Database Access Point application to use ODBC.
- For Interaction Server database DAP
  [settings]
  
  dbprotocol=odbc
  
  connection-string = <your connection string>
- For Database Event Logger DAP
  [logger-settings]
  
  delivery-protocol =odbc
  
  connection-string = <your connection string>
Determine the Connection string value.

Configure ODBC driver in connection string

Important

Genesys strongly recommends that you use latest versions of ODBC drivers that were released officially for your database. The main purpose of default drivers is backward compatibility with old database.

The actual driver name must be explicitly provided as a value of the connections-string option in the [settings] section (or [logger-settings] for the Event Logger DAP).

The value of connection-string is a list of key-value pairs separated by semicolons ( ; ).

To specify the actual driver, give it a value of driver=<driver_name>.
If your database server is not running on the default port (1433 for MSSQL and 1521 for Oracle), you must also provide the port number by adding port=<actual_port> pair to the the value of connection-string. For example, Driver=SQL Server Native Client 11.0;port=1433.

Important

For Oracle, ensure the LOB=T option is present in the connection string if it’s not specified in DSN (see the next section).

DSN

You can also have Interaction Server use a DSN that has been configured in your system. To do this, locate or create the connection-string option in the [settings] section of the DAP (the [logger-settings] section in the Event Logger DAP), and set it to DSN=<name_of_the_dsn>. With this method, the user name and password to connect to the database are taken from the settings on the DB Info tab and do not need to be provided in the DSN properties.

Configuring the DSN in ODBC

You can use the ODBC Data Source Administrator in Windows to create driver-specific DSN objects:

Open a command prompt.
Enter the command odbcad32 to open the ODBC Data Source Administrator.
Select the Drivers tab to view the ODBC drivers installed in your environment. Note the names of the available drivers.
Switch to the tab for DSN creation:
- If Interaction Server is started as a console application or by LCA (Local Control Agent), you must use the tab User DSN.
- If Interaction Server is started as a service by the SYSTEM account on Windows, you must use the tab System DSN.
Select Add and follow the vendor instructions to configure the DSN, specific to your database engine and the selected driver.

Important

For Oracle, ensure you check Enable LOBs in the Oracle tab.

Specify DSN in DAP

You can also have Interaction Server use a DSN that has been configured in your system. With this method, the username and password to connect to the database are taken from the settings on the DB Info tab and do not need to be provided in the DSN properties.

If you have created a DSN object, enter the value "DSN={name_of_DSN}" to the connection-string value. Otherwise, create appropriate DSN in your system. For more information, see Configuring the DSN in ODBC.

In the sample image below, the respective value is: connection-string=DSN=ci-vm410;

If you are using the same location for the main database and the Event Logger database, the values of these options might be identical. However, for performance or other reasons, you might have the Interaction Server main database and the Event Logger database installed in different locations.

Important

Genesys recommends that you do not use different database engine types simultaneously. For example, do not use Oracle for the main database and Microsoft SQL Server for the Event Logger database.

Additional information for Linux

Important

unixODBC driver manager is required to be installed in order to have Interaction Server use ODBC on Linux. For information on how to install unixODBC, refer to Installing ODBC on Linux.

If Interaction Server is running on Linux, the value for the option odbc-string in DAP objects might depend on where the driver's files were installed. For example, if you are not using a DSN, the driver name might be the actual location of the file, such as in the examples below:

Microsoft SQL Server: Driver=/opt/microsoft/msodbcsql17/lib64/libmsodbcsql-17.2.so.0.1
Oracle: Driver=/usr/lib/oracle/18.3/client64/lib/libsqora.so.18.1
PostgreSQL: Driver=/home/username/pgodbc/psqlodbc-version/lib/psqlodbcw.so

Tip

Refer to the unixODBC User Manual for instructions on how to configure DSN and test an ODBC connection using the isql tool.

Testing the ODBC connection with Interaction Server

Perform the following steps to test the ODBC connection:

Configure Interaction Server to collect the log into a text file with debug-level details. See the Options Reference for more information on available options.
Start Interaction Server and let it run to generate some events for the log.
Stop Interaction Server.
Open the log and review all parts that include the string odbc or the names of associated DAP objects. In the case of a successful ODBC connection, the log contains the following messages:
- Connection to main database:
```
Std 27126 New database connection opened (connection ID: 1)
Std 27113 Checking database integrity (connection ID: 1)
```
- Connection to Event Logger database:
```
Std 27126 New database connection opened (connection ID: 100001)
```
  Important
  - The connection ID number 100001 indicates a connection to the Event Logger database.
  - Interaction Server might open more than one connection to the database when necessary and as directed by the values of the option number-of-database-connections. Subsequent connection ID numbers are incremented accordingly.

Troubleshooting a failed connection

See below for quick troubleshooting hints for first-time connections. Make the necessary changes on the database engine side or in the DAP object.

All databases

On Linux, you might need to have the location of the ODBC driver listed in the environment variable LD_LIBRARY_PATH. This also applies to the unixODBC libraries location.

Microsoft SQL Server

Ensure the instance name is correct.

Oracle

Ensure the SID or ServiceName values are correct, and check the listener resolution in the file tnsnames.ora.
Ensure the setting of the environment variable TNS_ADMIN points to the folder where the file tnsnames.ora is located.
On Linux, the driver might require the following environment variables to be set:
export NLS_NUMERIC_CHARACTERS=""

export NLS_LANG=".UTF8"

export ORACLE_SID=<ORCL_actual_name>

PostgreSQL

Ensure that permissions to connect from a remote host are managed in the configuration file(s) pg_hba.conf.

Configuring Interaction Server DAP

Installing ODBC drivers