Skip to main content

CM/Phone

Introduction to CM/Phone​

CM/Phone is a ConSol CM extension which allows to integrate a telephone system using the TAPI 3 protocol, which is available on Windows operating systems. If CM/Phone is active, the users can initiate phone calls directly from the Web Client by clicking a phone number. When a customer calls, the users see the call on their screen and can choose to open the contact page or create a new case in the Web Client.

info

CM/Phone has to be licensed separately. Each client where CM/Phone is installed and active consumes one license of the type REST.

Technical background of CM/Phone​

The following figure illustrates how CM/Phone integrates with the telephone system and ConSol CM.

CMPhone_EN.png

The information shown in the pop-up window opened by CM/Phone is based on HTML template files which are located in the CM/Phone folder of the ConSol CM server. The templates are loaded by the CM/Phone client application during startup. You can customize them if needed.

Incoming calls​

The CM/Phone client monitors the telephone handset (i.e., the selected TAPI device, address or line) for incoming calls. When an incoming call is registered, a pop-up window with the phone number of the caller is shown and a contact with this phone number is searched in ConSol CM. If one matching contact is found, its name is shown. If there are several matching contacts, the user can select the desired one from a list.

info

The users need view permissions to the customer group of the contact to see its information.

The following features are available if a matching contact has been found:

  • Open the contact page
  • Create a case for the contact

The following features are available if no matching contact has been found:

  • Create a contact
  • Create a case for the newly created contact

When a new contact is created, the caller’s phone number is prefilled in the first contact field with the Phone number setting.

For missed calls, there is an option to call back.

Outgoing calls​

The users can start an outgoing call directly by clicking a phone number in a contact field with the setting Phone number. The CM/Phone application is started automatically by the browser and the phone number is passed to the telephone system as a command line parameter. The CM/Phone application creates an outgoing call via TAPI and quits immediately.

Usually the prefix phone: is set before the number for outgoing calls for interaction with TAPI. If required, you can configure another prefix (e.g. tel:) in the Windows Registry.

Installing CM/Phone on the server​

Perform the following steps to install CM/Phone on the application server.

info

The application server must be configured for working with exploded .war files.

  1. Copy the cm-phone.war folder to <JBOSS_HOME>/standalone/deployments.

  2. Overwrite the parameter ${deployment.auto.deploy.scanner:false} from the XML configuration file by adding the following line to the cm6-config.properties or cm6-cmrf-config.properties file:

    deployment.auto.deploy.scanner=true

  3. Adapt the configuration as needed (see Editing the CM/Phone templates).

  4. Restart the application server.

If CM/Phone was deployed correctly, you can see the welcome page of CM/Phone when accessing https://<CM_server>:<port>/cm-phone/

Installing CM/Phone on the client computers​

The users who want to use the CTI features provided by CM/Phone need to install the CM/Phone application on their computer. The installation file can be downloaded from the user profile in the Web Client.

Administrator permissions are required for the installation because an entry for CM/Phone needs to be written to the Windows registry. Before installing a new CM/Phone version, the users need to manually uninstall the previous version.

When opening CM/Phone for the first time, the users need to select the TAPI line to be used, enter the URL of the ConSol CM system and provide their username and password. These settings can be changed later in the Settings option of the CM/Phone icon in the task bar.

Configuring CM/Phone​

You need to perform several steps in the Web Admin Suite to configure CM/Phone:

  • Configure the contact fields for the phone numbers on the Contact fields page.
  • Define the display name of the contacts in CM/Phone on the Contact models page.
  • Configure the phone number format for each customer group on the Customer groups page.
  • Configure the prefixes for the phone numbers on the System properties page

Customizing the CM/Phone templates​

The layout and content of the contact details which are shown in the popup windows opened by CM/Phone are defined in HTML templates. They are saved in <JBOSS_HOME>/standalone/deployments/cm-phone.war/templates. The templates contain tags which are replaced with current values by the client application during a call.

info

These tags are case-sensitive.

The following templates exist by default:

  • CallNotification.html
  • ContactData.html
  • ContactList.html

They are used for the default language of the client system. To support additional languages, you need to create a folder with the name of the locale (e.g., de for German), which contains localized copies of the template files.

CallNotification.html​

This is the first template which is displayed as soon as an incoming call is detected by the CM/Phone client. This window only displays the calling number because at this point in the process there is no contact data available.

Available tags:

  • [phonenumber]: Phone number of the caller.
  • [calltime]: Time of the call.
  • [content]: Additional information to be displayed, e.g. a loading indicator during the contact search or an error message if the search failed (wrong username or password, etc.)

ContactData.html​

This template shows the detail of the calling contact if a matching contact is found for the phone number. You can add further tags using the contact fields defined in the respective contact model.

Available tags:

  • [phonenumber]: Phone number of the caller.
  • [calltime]: Time of the call.
  • [contactContent]: Display name of the contact as defined in the customer group settings in the template CM/Phone contact details.
  • [contact.id]: Internal ID of the contact in ConSol CM, can be used to create links into the Web Client.

ContactList.html​

If more than one contact is found for the phone number, a contact list is shown. It contains one row for each matching contact.

Available tags:

  • [phonenumber]: Phone number of the caller.
  • [calltime]: Time of the call.
  • [contactlistContent]: List of matching contacts as defined in the customer group settings in the template CM/Phone contact list.

Four buttons are configured in the standard templates:

  • Close: Closes the pop-up window.
  • Call: Starts an outgoing phone call to the calling number.
  • Open contact: Opens the contact page in the Web Client.
  • Create ticket: Opens the page to create a case in the Web Client.

The buttons refer to HTML links and can be customized as needed. Two types of links are available:

  • External link: Opens the respective page in a web browser, e.g. the contact page of the Web Client.

    https://<CM URL>/cm-client/contact/[contact.id]

    You can use contact data in the URL by passing it as parameter to create links to customer-specific web applications.

  • Internal link: Opens another page of the CM/Phone pop-up window.

    https://cmphone/<command>/?<parameter>

    Available commands:

    • contactdata: Used in the ContactList.html template. The user can select a contact to show its details (ContactData.html template). The contact ID is used as a parameter. 
      http://cmphone/contactdata/?[contact.id]
    • contactlist: Used to go back from the contact details (ContactData.html template) to the list of contacts (ContactList.html template). 
      http://cmphone/contactlist
    • call: Starts an outgoing phone call to the phone number of the contact. 
      http://cmphone/call
    • runcmd: Starts a local application on the client PC. The command line of the application is used as a parameter. In addition, contact data can be passed to the application, e.g.: 
      http://cmphone/runcmd/?dbapp.exe+userid=[customer.userid]
    • close: Closes the CM/Phone pop-up window. 
      http://cmphone/close

Advanced settings​

Adding debug logging on the client side​

You can activate debug logging on the clients using log4net by configuring the CMPhone.exe.config file in the installation path, usually <Program Files>\ConSol\CM Phone. If the user does not have write access to the Program Files directory, you need to set the log file path to another folder, e.g.:

<file value="${USERPROFILE}\phone.log" />

Registering CM/Phone​

If the client application cannot be installed by the users themselves because of insufficient permissions, it can be distributed by a system administrator. In that case, the application needs to be registered on the client as phone: protocol handler by creating the appropriate Windows registry keys:

[HKEY_CLASSES_ROOT\phone]
//Please make sure to set the space in URL Protocol, otherwise it will not work.
[HKEY_CLASSES_ROOT\phone\DefaultIcon]
@="C:\\Program Files (x86)\\ConSol\\CMPhone\\cmphone.ico"
[HKEY_CLASSES_ROOT\phone\shell]
[HKEY_CLASSES_ROOT\phone\shell\open]
[HKEY_CLASSES_ROOT\phone\shell\open\command]
@="C:\\Program Files (x86)\\ConSol\\CMPhone\\cmphone.exe" //(example)

Using the REST API for testing​

CM/Phone uses the REST API to request data from the ConSol CM server. You can use a REST client in the browser or tools like curl to check if the data needed by CM/Phone is present in the system, e.g. if a contact with a certain phone number exists:

https://<CM_SERVER_URL>:<CM_PORT>/restapi/units/?phoneNumber=[phonenumber]