CRM Integration with QueueMetrics

SugarCRM and VTigerCRM are two widely used CRM software packages used to track contacts and opportunities that are widely used by call-centres worldwide. QueueMetrics can be easily integrated with them thanks to its ability to automatically open a specific URL from the agnet’s Live agent page. When integrated, any new call answered by an agent opens the associated CRM contact page, if present, or pre-fills a new form with the incoming caller ID.

Prerequisites

  • A working QueueMetrics instance

  • One of the supported CRM packages, already installed and working

  • A working PHP+Apache instance (usually the same where the CRM is running)

  • A copy of the OpenQueueMetricsAddOns package available at https://github.com/Loway/OpenQueueMetricsAddOns

Integration with SugarCRM

Integration with SugarCRM is implemented by mean of an external script that is to be copied on the Apache webroot folder. The script is supplied within the addon library present on https://github.com/Loway/OpenQueueMetricsAddOns . When properly configured, the QueueMetrics agent call history page opens an external URL for each taken call. This feature is be used to trigger the provided PHP script. The script searches among contacts in the SugarCRM database using the current caller-id, and opens either the caller’s record, if present on SugarCRM database, or preloads a new contact page filling in the calling party number.

The steps for installing and configuring the script are reported below. We suppose to use the Apache webserver where SugarCRM is running. We install the script on the Apache webserver main document root:

  • Download the 'nusoap library from http://sourceforge.net/projects/nusoap

  • Extract the source zip on the main document web root and rename it to "nusoap", chown to the 'apache' user and set proper permissions

  • Copy the 'QueueMetrics_SugarCRM.php' file on the web root folder, chown to the 'apache' user and set proper permissions

  • Generate a 'queuemetrics' user for SugarCRM. The 'queuemetrics' user should be able to perform searches and access contacts. Annotate the password generated by SugarCRM (when creating the 'queuemetrics' user, you must use a valid e-mail address where SugarCRM will send the password)

  • Open the 'QueueMetrics_SugarCRM.php' file and edit the variables:

    • $server_url (set it to your SugarCRM server address/name)

    • $username (the user you created on the step above)

    • $password (set it to the password generated by SugarCRM for the queuemetrics user)

  • Edit the 'configuration.properties' file you can find on the QueueMetrics installation folder. Look for the default.crmapp key and change it in order to point to your Apache server. The URL should contain a reference to the current caller ID, for this reason, the dynamic token [C] must be included. The URL will be something like:

http://10.10.1.1/QueueMetrics_SugarCRM.php?callid=[C]

  • Restart QueueMetrics and log on as agent. Open the live agent page.

Each time a new call is shown in the agent page, your browser will open the SugarCRM contact page, if any.

The very first time the contact page will open, you’ll be asked for login on the SugarCRM. This is because you want to access to SugarCRM with your proper username and password and not as the 'queuemetrics' user.

A more advanced configuration

You may want to avoid the SugarCRM authentication procedure that happens when the agent receiveds the first call. To do this you need to implement some logic into the 'QueueMetrics_SugarCRM.php' script where you retrieve the agent’s username and password before redirecting to the SugarCRM page. The logic is not already implemented because we don’t know how agent codes and SugarCRM username and passwords are defined in your organization, but we can provide some hints on how to retrieve the needed information from QueueMetrics.

In order to propagate the agent code to the script, you need to change the URL you defined in the 'configuration.properties' file adding the dynamic agentcode parameter. You should have something like:

http://10.10.1.1/QueueMetrics_SugarCRM.php?callid=[C]&agentcode=[A]

Don’t forget to restart QueueMetrics and logoff and logon again to the agent page. As soon as the script will be called, the variable $agent in the script will be populated with the calling agent code. What you have to do is to implement some logic that, starting from this code, retrieves the username and the password used by that specific agent to authenticate on SugarCRM.

if ($agent != '') {

    // Insert here your code for agent SugarCRM username and password retrieval
    // The default behavior is to use a single account for all agents
    // Using default behavior requires agent authentication on SugarCRM pages

    // $username = Sugar CRM username for this agent
    // $password = Sugar CRM password for this agent
    // $autologon = TRUE;
}

You need to properly set the $username and $password variables, then comment out the $autologon flag row. The script will generate a SugarCRM session that will be inserted in the URL used to open the contact page.

Integration with VTigerCRM

Integration with VTigerCRM could be done in two different, mutually exclusive ways.

Integrate with QueueMetrics live page

Integration with VTigerCRM is implemented through an external script to be copied on the Apache webroot folder. The script is available on the addon library available at https://github.com/Loway/OpenQueueMetricsAddOns . When properly configured, the QueueMetrics agent call history page opens an external URL for each call taken by the agent. This URL triggers the provided PHP script. The script searches among contacts in the CRM database using the current caller-id, and opens either the caller’s record, if present on the CRM database, or preloads a new contact page filling in the calling party number.

The steps for installing and configuring the script are reported below. We suppose to use the same Apache webserver where the VTigerCRM is running. We install the script on the Apache webserver main document root:

  • Download the 'Php Zen json libraries' from http://framework.zend.com/releases/ZendFramework-1.6.1/ZendFramework-1.6.1-minimal.zip and uncompress them

  • Update the PHP shared library search path (add the Zen Json folder to the include_path key in the php.ini file)

  • Install the PHP Pear framework and type pear install HTTP_Client from a command line shell

  • Copy the 'QueueMetrics_VTigerCRM.php' script to the webroot folder

  • Create a 'queuemetrics' user on VTigerCRM, with permissions to look at contacts and retrieve the required access key generated by VTigerCRM on the user page settings

  • Open the 'QueueMetrics_VTigerCRM.php' file and edit the variables:

    • $server_url (set it to your VTigerCRM server address/name)

    • $username (the user you created on the step above)

    • $accessKey (set it to the 'accessKey' generated by VTigerCRM for the 'queuemetrics' user)

  • Configure QueueMetrics to open an external URL for each received call. The URL should contain the caller number as callid parameter

http://10.10.1.1/QueueMetrics_VTigerCRM.php?callid=[C]

  • Restart QueueMetrics and log on as agent. Open the live agent page.

Each time a new call is shown in the agent page, your browser will open the VTigerCRM contact page, if any.

The very first time the contact page will open, you’ll be asked for login on the VTigerCRM. This is because you want to access to VTigerCRM with your proper username and password and not as the 'queuemetrics' user.

Integrate with VTigerCRM PBX Manager Module

VTigerCRM already provide a PBX Manager module that integrates with your Asterisk PBX. With the current implementation (VTiger CRM 5.4.0) the PBX Manager is able to open a popup whith caller id information each time a new call is directed to the extension configured by a VTiger user. The PBX Manager is able also to enable a handy click-to_call feature (that is out of the scope of this document to describe).

Unfortunately, the PBX Manager does not handle calls coming from a queue. You need to make a little modification to the VTigerCRM PBX Manager module source code in order to have the popup shown for calls coming from queues, as explained below.

First of all you need to activate and configure the PBX Manager Module on VTigerCRM.

  • Log in to the VTiger panel as administrator

  • Go to the CRM Settings, from the top right-most icon on the page

  • Click on "Module Manager"

  • From the list you have on that page, click on the hammer icon present on the PBX Manager row. This lets you to access to the PBX Manager settings

  • Fill in the relevant Asterisk information: server IP, AMI port, AMI username and password. Stick with 1.6 Asterisk version (we don’t provide Asterisk 1.4 integration)

  • Press Update

  • Go to the user preferences page and fill the section 7: 'Asterisk Configuration' with your internal extension. Enable the "Receive Incoming Calls" tickbox

You then need to modify the script responsible for reading Asterisk AMI events and inject calls events on the VTiger database.

  • On the VTiger webroot folder, open the file AsteriskClient.php present on the /cron/modules/PBXManager subfolder.

  • Look for the asterisk_handleResponse2 function. There is a set of if/else block.

if(
    $mainresponse['Event'] == 'Newexten' && (strstr($appdata, "__DIALED_NUMBER") ||
        strstr($appdata, "EXTTOCALL"))
  ) {
    ...
    ...
    } else if($mainresponse['Event'] == 'OriginateResponse'){
    ...

Change it inserting a new else block as reported below.

if(
    $mainresponse['Event'] == 'Newexten' && (strstr($appdata, "__DIALED_NUMBER") ||
        strstr($appdata, "EXTTOCALL"))
  ) {
    ...
    ...
    } else if($mainresponse['Event'] == 'AgentCalled'){

            $uniqueid = $mainresponse['Uniqueid'];
            $channel = $mainresponse['ChannelCalling'];
            $plits = explode('/', $channel);
            $callerType = $splits[0];

            $splits = explode('/', $mainresponse['AgentCalled']);
            $extension = $splits[1];

            $parseSuccess = true;
    } else if($mainresponse['Event'] == 'OriginateResponse'){
    ...

Save and run the script as by VTiger documentation.

Each Agent could log-in on the QueueMetrics agent page and, through this, log-in on the preferred queues specifying the internal extension already set on the VTiger user preferences. As soon as a new call coming from the queue is received on that extension, a popup is presented in the VTiger pages.