CTI technology

Introduction

This article describes the configuration of the telephony connection using CTI technology.

CTI stands for Computer Telephony Integration. This modern technology links the worlds of classical telecommunications (TC) and information technology (IT). Telephones are only used to transmit speech. The connection is established and controlled, on the other hand, via computers. CURSOR-CRM provides the user interface for the CTI clients.

Figure: Example of a CTI landscape

Architecture

The CTI connection is implemented on the server side. This allows central communication of the CRM system with the telephone system and the central configuration of all components. This makes it possible to implement the telephone connection with the Web Client and to log missed calls, although the user is not logged on to the system.

The CTI server connection is handled by an intermediate component, the CTI agent server. Separating the server from the application server is important to ensure the CTI connection in cluster operation and not to load the application server with additional threads for CTI events when there are lots of users.

1. Client: The user can make a phone call through the application and is notified of incoming phone calls with caller details

2. Application server: Requests from the client are forwarded to the CTI interface. Incoming calls are persisted and managed in the task list

3. Database: The configuration of the CTI server, the telecommunication system and the individual telephones per user is stored here

4. CURSOR CTI server: An own application server which

   1. monitors all registered phone servers and telephones,

   2. forwards requests from the user,

   3. handles communication with the telephone server via various CTI protocols,

   4. encapsulates different PBX types as JTapi implementation.

5. CTI server: The telephone system can be addressed e.g. via CSTA protocol

Installation

CTI application server

The CTI application server uses the same version as the CRM application server. Please refer to the installation manual for installation instructions. The CTI server does not require any configuration of a database connection. The certificate configuration must be taken over from the CRM application server.

The production system and the test system each require their own CTI application server. We recommend that you install the CTI application server and CRM application server on the same system and adjust the port range of the CTI application server accordingly.

The web application cursor-csta-VERSION.war must be copied from the installation package under ../csta/deploy into the deployment directory.

The service of this CTI application server can be restarted every night so that the CTI interface can be reinitialized.

The default settings from "Installing the Application Server" are completely sufficient for the CTI server:

Name Affix

To use the CTI interface, the CTI interface must be purchased as a license and imported into the module management.

After a client restart, the system settings and CTI-specific entities are visible in the administration menu and the configuration pages in the administration console.

System Preferences

The CTI application server communicates with the CRM application server via an encrypted SLL connection. The call configuration must be stored in the system settings under CTI Configuration:

• CTI server: The host name incl. https port. Depending on port setting (X8443)

• CTI dialog: Incoming calls are displayed as a notification in the lower right-hand corner of the screen or directly as a CTI dialog.

• Application server user name: A technical user created as an employee dataset for the CTI configuration in CURSOR-CRM (the CTI application server logs on to the CRM application server). The technical user requires administration rights (rights group, default: "ADMIN") to access the telecommunications data of all employees, contact persons and business partners.

• Application server password: The password of the technical employee. The encrypted hash password from the database is required here. The plain text password is required for Kerberos authentication.

Telephony configuration

The configuration is performed in the Telephony Configuration node in the admin console.

Figure: Telephony configuration

Changes to the settings regenerate the telephone numbers for the CTI interface. The Update all communication entries button can be used to regenerate all telephone numbers after a data transfer. This action can also be triggered externally via the IvocationServlet.

The following settings are taken into account when generating the CTI-compliant number.

• TAPI Prefix: Specifies the characters for the TAPI prefix. Usually 0.

• Use TAPI prefix: Specifies whether the TAPI prefix is also transferred from the telephony system during inbound calls.

• Activity type (phone in): Specifies the activity type when an activity is created during an inbound call.

• Activity type (callback): Specifies the activity type when an activity is created after a callback during an inbound call.

• Internal number length: Specifies the length of extensions within the company. This is required for correct number recognition.

Exclusion list for inbound calls

Telephone numbers stored in the exclusion list are ignored during inbound processing. These could be, for example, internal extensions within the company. The exclusion list is maintained using special input fields. Every user can decide in User Preferences > General whether he wants to use the exclusion list. In addition, a convenient function is implemented that allows you to add the phone numbers of all employees to the exclusion list.

Configuration of the telephony inbound dialog

The configuration of the dialog for inbound calls can be found in the administration console under Telephony Inbound Dialog Configuration.

The administrator can customize texts for the business partner, contact person and employee display. The available fields can be supplemented in a separate search container. The display of a report can be activated and user groups specifically stored.

A prompt appears for any unsaved changes when exiting the configuration mask.

Report configuration

Reports can generally be activated via the option Display reports. This changes the layout of the inbound dialog from 600x400 to 900x700 pixels. Reports can be stored for each configuration group or system-wide for the entities ‘Business Partner’, ‘Contact Person’ and ‘Employee’. If no report is defined for an entity, the inbound dialog displays an empty report area. The "CTI Contact Person Report" is available by default. The report can be overridden for customer adjustments.

If a group configuration matches the system configuration, then it will be removed. It is not possible to create a duplicate configuration and a relevant message dialog will be displayed. The delete button becomes active, once a report configuration is selected in the table. Any configuration can be removed after consultation.

The optimal report size is 372ptx444pt without margins.

The report should not activate the option ‘Enlarge with Overflow’ for any field to ensure a pixel-perfect layout and to prevent scroll bars. Sub-reports are possible, but should be avoided for reasons of runtime and changes in the layout, depending on the number of dependent data.

Reports are loaded with a fixed delay after the initial load, so that multiple clicks in the list will not load a report each time. The delay is 250ms.

Search configuration

The system default search container for inbound (name 'C0CtiInbound') can be overridden or copied by the administrator.

The CTI search can only be supplemented with fields in the table search. Structural changes to the search may lead to runtime errors.

You can select the new search in the inbound dialog configuration. When saving, the text scripts are checked for the fields used.

Script for dialog texts

The fields from the search are copied completely as variables. The ‘.’ (full stop) is replaced by ‘_’ (underscore).

Example

Match code [MatchCode.Customer] -> MatchCode_Customer

The text to be created for the CTI dialog must be appended to the result variable:

result.append(I18nUtils.i18nEntity("Customer", SessionConstants.LOCALE)).append(": ").append(MatchCode_Customer);

The following constants are available:

• SessionConstants.USER: User token

• SessionConstants.LOCALE: The language used

Labels

Using the script method I18nUtils.i18nCustom(String, Locale), customer-specific texts can be used independently of their language. The 'Labels' button displays an I18n dialog in which existing translations can be edited and new label keys can be created.

Monitoring

Automatic initialization

When the application server is restarted, a timer is started to initialize the CTI server. This attempts to transfer the CTI configuration to the CTI server and register for CTI events there. The initialization is repeated until the CTI server can be reached and the initialization has been successfully completed.

In the administration console, under Timer, activate "Initialize" and set the time period. A setting of 60 seconds is recommended.

If the CTI server cannot be reached in the meantime and a connection error occurs during telephone actions, the initialization timer resumes work and tries to configure the CTI server cyclically.

Automatic BPM monitoring

A time-controlled server-side process can be used to monitor the availability of the CTI server. The process cyclically checks the reachability of the CTI server and can inform the administrator depending on the error.

The "CTI Monitor" process is available by default. If problems occur, the administrator is informed by a system message in CRM and, if necessary, by email.

The administrator for the notification must first be entered in the global variable "C0CtiNotificationUser" with the user token.

The system mail configuration must be set in the CRM system preferences.

The process is set up at the customer with its ID (C0CTI monitor) under the time-controlled actions in the administration console:

Logging

All logs on CTI are recorded on the server side in a separate log file.

• CRM-JBoss/server/standalone/log/csta.log

• CTI-JBoss/server/standalone/log/csta.log

Debugging information can be enabled or disabled using the command 'jboss-logging.bat csta true/false'.

CTI configuration

The configuration entities for CTI can be found in the administration menu under CTI Administration. After the configuration has been completed, the client must be restarted so that all CTI functions are available to the user.

CTI Server

The login data for the CTI server or telephone system is stored here. The type determines the type of CTI connector:

• SIMULATION: A simulation of the telecommunications system via a web interface (see ...)

• CLARITY: Connection of various telephony interfaces via the Clarity connector

• CLARITY_CCC: Connection of the Clarity telephony system

• SIEMENS CAP 3: Connection of a Siemens HiPath 4000 system via the Siemens CAP3 server or connection of the CSTA interface of the Open Scape Voice telecommunications system.

• SNOM: Connection of the CSTA interface of Snom phones (will shortly not be supported)

Clarity connector

TAPI driver

The connection to a server-side TAPI interface requires a server-side usable "3rd party" TAPI driver in version 2.1 or 3.1 in the 64bit variant. The tapi driver is provided by the telecommunication system service provider (e.g. Avaya, Cisco) and usually has to be licensed separately. In the CRM system there may only be exactly one configuration for the TAPI connector! The driver should only be used by the CTI connector, as a parallel TAPI application may interfere with access to the TAPI driver. The extensions provided in the TAPI driver must be permanently available, even if the users can log off the telephone terminal.

This interface only runs under Windows and is based on a DLL that communicates with Windows TAPI. The log path for the DLL is determined from the JBoss configuration and can be found at /standalone/log/Tapi3Provider.log.

The CTI server configuration requires the following information:

The CTI device configuration is created and assigned to each employee. The device ID must match the address in the TAPI driver.

Clarity telephone system

This connector connects directly to the Clarity telephone system in conjunction with the Clarity Communication Client.

The CTI server configuration requires the following information:

The CTI device configuration is created and assigned to each employee. The device ID must match the participants in the telecommunication system configuration.

Avaya AES telephone system

This connector connects directly to Avaya's telephone system, the Avaya AES and is based on Avaya Enablement ServiceAura® Application Enablement Services programmed by Avaya Inc.

The CTI server configuration requires the following information:

The CTI device configuration is created and assigned to each employee. The device ID must match the participants in the telecommunication system configuration.

Caseris telephone system

This connector connects to the Caseris telephone system via the Caseris web server.

The CTI server configuration requires the following information:

UC Integration Server

To connect to the OpenScape Voice telephone system in conjunction with the Enterprise Communication Center for call centers, communication takes place via the middleware, the UC Integration Server.

This provides only the functions required by the customer and is connected by means of web socket communication via a special Clarity connector.

The CTI server configuration requires the following information:

The CTI device configuration is created and assigned to each employee. The device ID must match the participants in the telecommunication system configuration.

Unify CAP-Server / Open Scape Voice

The CAP server from Unify (formerly Siemens) is an additional component that provides the CSTA interface for different Unify telephone systems. If several telephone systems are set up in the CAP server, a separate CTI server configuration must be stored for each port, otherwise communication may be disrupted.

The new Open Scape Voice telephone system has a direct CSTA interface, but this is not compatible with the Unity-JTapi connector.

The CTI server configuration requires the following information:

The CTI device configuration is created and assigned to each employee. The device ID must match the participants in the telecommunication system configuration.

Simulation

The simulation creates its own layer in the CTI server, which simulates events of the telephones on a web interface and thus allows the behavior of the CRM system to be tested.

Test configuration

The connection data of the CTI agent server must be entered in the system settings. TECH_USER can be used as the technical user.

A separate dataset is created as a CTI server for the simulation:

• Type: SIMULATION

• Server: TEST

The CTI telephone configuration is stored for this test server for some employees. The employee is linked to the dataset in the sub area.

• CTI server: TEST

• Device ID:<Extension>

After setup, a new login to the client is necessary so that the CTI connection can be used for the configured employee.

Web interface

The web interface of the simulation is provided via the web layer of the CTI server. The URL is:

https://<server>:<X>8443/cti/simulator.xhtml

In the simulator, all configured CTI devices are displayed as tabs. The input field for inbound or outbound telephone numbers is evaluated each time the button is clicked.

• Originated: This simulates an outbound call made on the phone

• Ringing: This simulates an inbound call on the specified phone number

• Group Transfer: This is call pickup for telephones in a group circuit

Pressing this button generates a new call in the simulator, whose status can now be changed:

• Connected: Now the phone call was answered. Both parties are conducting a call.

• Held: The call is placed on hold, e.g. to initiate a transfer.

• Invalid: The call was ended by the other party, but your own telephone was not disconnected. You cannot start any other actions on the telephone until your own telephone has been disconnected.

• Disconnected: Your own phone has been disconnected.

The currently active call should always be removed after the test.

Test scenarios

The test scenarios describe the flow of the buttons that must be pressed, the change of status in the CTI call entity and the display in the CRM system.

The telephone set up for the USER employee has the telephone ID 100. A contact person in the system is given extension 123.

Missed call

1. Generate call
   

   1. In the web interface, switch to tab '100'

   2. Enter the number 123 in the telephone field

   3. Press the Ringing button

2. Signal a call
   

   1. The simulator shows the call with the number and the status Ringing

   2. In the client, a new entry is created for the USER user in the task list under Call log

   3. The CTI dialog opens and shows the contact person and their data

3. Hang up call
   

   1. Now press the DISCONNECTED button in the simulator

   2. Only the Remove Call button is available

   3. The CTI dialog closes

   4. The task list retains the entry. The status changes from Ringing to Missed

4. Remove call
   

   1. The call is removed in the simulator via the Remove Call button

   2. In the task list, the CTI dialog can be reopened via the Open button on the missed call

   3. By clicking the Remove button, the missed call also disappears from the task list.

5. Find call
   

   1. You can search for the missed call in the administration menu under CTI Administration > CTI Call

   2. The contact person found is linked to this set

   3. The status is set to Missed

Accepted call

1. Generate call
   

   1. In the web interface, switch to tab '100'

   2. Enter the number 123 in the telephone field

   3. Press the Ringing button

2. Signal a call
   

   1. The simulator shows the call with the number and the status RINGING

   2. In the client, a new entry is created for the USER user in the task list under Call log

   3. The CTI dialog opens and shows the contact person and their data

3. Answer call
   

   1. In the CTI dialog press the Answer button

   2. The Answer button changes to Hang up. Transfer becomes active

   3. In the simulator the status of the call changes to CONNECTED

   4. The task list shows the current call with the status Connected

4. Hang up call
   

   1. In the CTI dialog press the Hang up button

   2. The dialog remains open. The button changes to Recall

   3. In the simulator the call has been removed

   4. The call has been removed from the task list

5. Find call
   

   1. You can search for the missed call in the administration menu under CTI Administration > CTI Call

   2. The contact person found is linked to this set

   3. Call times are maintained

   4. The status is set to Finished

Internal telephone call

1. Initiate a call
   

   1. Open the contact person

   2. Press the telephone button next to the telephone field

2. Monitor the telephone call
   

   1. A new call with the number and the status ORIGINATED was created in the simulator

   2. The task list displays this call

   3. The CTI dialog does not open

3. Answer the call
   

   1. In the simulator, use the CONNECTED button to accept the call

   2. The status in the task list is updated

   3. The telephone button on the telephone field turns red

4. Hang up the telephone call

   1. Hang up the telephone call using the telephone button in the telephone field

   2. In the simulator the call has been removed

   3. The call has been removed from the task list

5. Find call
   

   1. You can search for the missed call in the administration menu under CTI Administration > CTI Call

   2. The contact person is linked to this set

   3. The status is set to Finished

User interaction

If it is not allowed for employees in the company to see who and when a telephone connection was established, we recommend hiding the call log in the mask configuration.

Task list

Active or missed calls are displayed to the user in the notification dialog.

All missed calls can be displayed in the call log.

Each entry can be opened to display additional information. The CTI dialog opens here. Entries that are no longer required can be removed.

Notification

If the CTI dialog is deactivated in the system settings, a notification appears at the bottom right of the screen in the event of a new inbound call.

The contact person found, the telephone number and the call time are presented to the user. Clicking on the contact person name (link) opens the CTI dialog with additional information. If the number could not be assigned to a contact person or business partner, the notification only shows the number and the call time.

Dialog box

If the CRM notices an incoming call, it opens a window that displays the caller and offers actions within the CRM.

This window can be configured.

This is described in the article Dialog box for processing inbound calls.

The CTI dialog can be enriched with a report with additional information. A separate report must be defined for contact person, business partner or employee.

Open CTI dialog via CRM link

The server-side CTI integration does not work with all telephone systems, since no CTI interface is available there. For this problem, however, the CTI inbound dialog can be opened on the client side using the CRM link functionality. Instead of transferring the table name and the primary key, the telephone number is transferred to CRM.

As a program call:

java -jar ..\client\lib\LinkGateway.jar "EVIJET://'TAPI&no=00641400000'"

As a hyperlink:

EVIJET://'TAPI&no=00641400000'

Figure: CTI call via a link

The telephone actions are only available in the dialog if the CTI interface is configured for the current user.

Extension of number recognition

Sometimes numbers are not sent in E164 format, so that the leading '00' for the country code are trimmed. Addition of the missing zeros can be activated by a system setting in the database (example: Oracle):

INSERT INTO PropertyMapper (Pk, id, property, propertyType, Active, CreateUser, UpdateUser, CreateDate, UpdateDate, propertyValue)
VALUES ('TELEPHONY_LINK_COUNTRY_FIX_Pk', '/de/cursor/jevi/common/telephony/TelecomPreferences$!!$TELEPHONY.LINK.COUNTRY.FIX', '', 'SYSTEM', 1, 'TECH_USER', 'TECH_USER', sysdate, sysdate, 'true')

Telephone field

• If a contact person has a stored telephone number, the telephone button is available in the telephone field and on the contact person field of the activity.

  

• If a telephone call is made, the status of the telephone button changes to red.

  

Reports

All calls are logged in the CTI Call entity. The administrator can search for these calls or configure an appropriate report for them and make it available to users. The administrator can search for all telephone calls and access information via the administration menu.

Contact persons, business partners or employees found for the specified telephone number are linked in the sub area. Recorded activities are also linked to the CTI call. Using the mask configuration, the link can be displayed in the sub area. The call data cannot be changed at a later date.

Representative (deputy)

The table gives an overview of how the system behaves after the deputy has registered.

Type	Login (normal)	Login as a deputy	Comments
Broadcast call	Restriction to the group of the own employee	Restriction to the group of deputies	the read status is always based on the logged on user, never on the deputy user
Notification	Search for employee is own user	Search for employee is deputy
Calls	Search for employee is own user	System preference:	The user cannot make calls via the CRM, all CTI actions are deactivated Only the missed calls of the deputy are displayed No CTI dialog is displayed for incoming calls (own telephone)
		System preference:	The CTI functions are activated The user uses his/her own telephone (as always, since he/she does not change workstations) The call log shows your missed calls and the missed calls of the deputy The call log contains the active call from the own telephone The CTI dialog is displayed for incoming calls (own phone only)

Functional tests

All basic settings should have been checked using the simulator. Now the tests on the telephone system can start.

Test scenario 1

1. Loading an employee with telephone extension

2. In the telephone field, press the Dial button
   

   1. Your own telephone dials the employee's extension number

   2. The telephone button changes to Hang Up

   3. The task list contains a new entry for the current phone call

3. Now press the Dial button again without answering a call
   

   1. The phone call is ended

   2. The telephone button changes to Make call

   3. The task list entry is removed

Test scenario 2

1. Loading an employee or contact person with a mobile phone number

2. Calling the mobile phone via the Dial button
   

   1. Your own phone dials the mobile number

   2. The telephone button changes to Hang Up

   3. The task list contains a new entry for the current phone call

3. Answering the call on your mobile phone
   

   1. The status of the task list entry changes

4. Hang up the call on your mobile phone
   

   1. The status of the task list entry changes

5. Hang up your own telephone
   

   1. The phone call is ended

   2. The telephone button changes to Make call

   3. The task list entry is removed

Test scenario 3

1. Calling your own telephone from another telephone
   

   1. Your own telephone rings and displays the number

   2. The CTI dialog opens and shows the number

   3. If the other employee is configured correctly, he is displayed in the CTI dialog

   4. The task list shows a new entry with the status Ringing

2. Hang up the handset on the other telephone
   

   1. Your own phone no longer rings

   2. The CTI dialog closes

   3. The task list entry has been updated to the Missed status.

3. Use the mouse to open the CTI dialog over the task list entry
   

   1. The Recall button is available

4. Remove missed call
   

   1. Click on Remove to remove the entry from the task list.

   2. The CTI dialog must be closed separately

Test scenario 4

1. Call your own telephone from your mobile phone (the number is stored with a contact person)
   

   1. Your own telephone rings and displays the number

   2. The CTI dialog opens and shows the number and the contact person data

   3. The task list shows a new entry with the status Ringing

2. Use the button to Answer the call
   

   1. Both telephones are now connected to each other

   2. The CTI dialog remains open

   3. The status in the CTI dialog and the task list is changed to Connected

3. Enter a new activity
   

   1. The activity is created with the type TELEIN

   2. The contact person is linked as an Activity with

4. End the call
   

   1. The status of the CTI dialog has been updated

   2. The task list entry is no longer displayed

Generation of telephone numbers

The part described here affects CTI phone behavior. For inbound and outbound calls, the country code is retrieved from the system owner or from the TAPI location linked to the employee. The phone numbers are composed correctly only if these entries are neatly maintained. The setting of the TAPI location (e.g. country code) overrides the setting of the system owner and the system defaults from the administration console (e.g. TAPI prefix).

Use of the TAPI location per employee

A TAPI location has the following settings:

• The user's country code in the format +country code
  Example for Germany +49

• The user's location identifier
  Example for Giessen 0641

• The basic call number of the user
  Example for the CURSOR Software AG 40000

• TAPI Prefix
  if a prefix must be dialed to receive an outside line

• Use outside line access (telephone input)
  delivers the outside line access to the application or this is removed beforehand

At the telephone input, the incoming phone number is converted into a "normalized" format and searched for in the TAPI number fields in the database.
The following setting in the PropertyMapper is important for the recognition of internal calls:

Id = '/de/cursor/jevi/common/telephony/TelecomPreferences$!!$CTI.EXTENSION.LENGTH'

In the standard version delivered, the length of the internal number is configured to 3.

Use of the Tapi location:
The TAPI location is implicitly used and controls the following actions:

• searching for inbound calls

• dialing outbound calls

• displaying the telephone number fields

  • the parts of the phone numbers that match the settings of the location are suppressed

  • depending on the individual location, the country dialing rules are used, whereby special logics only exist for the saved countries. All others receive standard behavior (analog to the setting for Germany)

Example of displaying phone numbers at different locations

Four phone numbers are shown in the system as they are displayed in different TAPI locations. The representation in the tree uses the composite form, which would also be used in a letter.

Here are the numbers:

The location of Marburg in Germany Test Location +49 (6421) 40000 gives the following "dialable" display:

The location of TestCity in Russia Test Location +7 (6421) 40000 gives the following "dialable" display:

The location of TestCity in USA Test Location +1 (6421) 40000 gives the following "dialable" display:

Configuration

Location descriptions

System owner

• The settings for the phone number for the system owner are made implicitly by maintaining the system owner's main phone number.

• The settings for using the TAPI Prefix for the system owner are made in the Admin Console (Miscellaneous -> Telephony Configuration)

User

• The settings are made in the TAPI location sub area

• Each user can have a maximum of one TAPI location.

• If more than one location is configured, an error is logged on the server and the setting of the system owner is used.

• If no location is configured, the setting of the system owner is used.

Logics

The following country-specific logics are currently stored:

Note

The standard syntax covers ~80% of all other countries.

Details can be found from the ITC. The document Dialing procedures (international prefix, national (trunk) prefix and national (significant) number) (in accordance with ITU-T Recommendation E.164 (11/2010)) as amended on 15.12.2011 can also be found there.

Technical notes on the storage format

A "normalized" format is used to store the CTI number. The presentation always corresponds to the default or reference country Germany.

The prefix is stored without leading zeros, these are trimmed by the application when saving; the phone number is not displayed in the application.

Interface Overview

Interfaces that write data into the telecommunications fields have the options described below.

Simple filling of the phone number

The phone numbers are only written to the respective base fields (PhoneNoBase, FaxNoBase, MobilePhoneBase). All other fields remain empty or contain the empty key.
The CTI number and the displayed composite number (composed) can be filled by calling the InvocationServlet job "generateCTINumbers".

Filling the phone number into the subfields

The phone number is written into the individual fields <Type>Country, <Type>City, <Type>Base and <Type>Extension, where <Type> stands for PhoneNo, FaxNo and MobilePhone.
The CTI number and the displayed Composed number can be filled by calling the InvocationServlet Job "generateCTINumbers".

Disable the logic

This option is also available. The data is entered in the fields. They are only concatenated in the surface.
The CTI functionality cannot be guaranteed.
This option can be activated or deactivated under the menu item Options -> System preferences-> General -> "Use logic for generation of phone number” option.
The default is activated logic.