Integrate 3CX with SugarCRM

IMPORTANT: This guide has been tested with SugarCRM 5.1.0 to 6.4.2 (see system requirements for version details). The provided customizations to launch outbound calls from the SugarCRM web interface cannot be imported into a SugarCRM Trial version, but you can manually create the custom fields as described in this document.

The SugarCRM Plugin

The 3CX CRM Integration module provides out of the box integration with SugarCRM. The SugarCRM plugin allows looking for contact information in the Contacts, Leads and / or Accounts tables using all the phone related fields, showing the contact details in a screen pop-up, opening the contact record in SugarCRM, creating a new contact if it has not been found, and saving the call information in the contact’s history.

Launching outbound calls from the SugarCRM web interface is really easy: just import the customizations provided and you will have “click to call” links when you are viewing a Contact, Lead or Account, for every phone field. Just follow the link and a new call will be triggered and automatically connected to your extension!

System Requirements

The SugarCRM plugin uses the soap Web Services API, so it works with any SugarCRM version that supports that API. At the time this article was written, the supported SugarCRM versions are: 5.1.x, 5.2.x, 5.5.x, 6.0.x, 6.1.x, 6.2.x, 6.3.x and 6.4.x (Enterprise, Professional or Community Edition).

In order to launch outbound calls from the SugarCRM web interface, you need to have the TCP port 5536 free.

Configuring the SugarCRM Plugin

General Configuration

In order to enable the integration with SugarCRM, check the “Enable SugarCRM Plugin” option.

If you also want to automatically create call logs in the contact’s activity history, you must check the “Store Call Information in SugarCRM” option. When this option is set, the plugin will open a new a call log record in SugarCRM after the call has ended. If you want the new call log record to open when the call starts, follow the instructions described in the “Contact Lookup” section. Please note that the call duration will not be pre-populated if you have set the call log record to open when the call starts.

Login Information

Now, you need to fill in the Login Information section with your SugarCRM URL, the connection timeout (in seconds), the user name and password. The SugarCRM URL setting should be set to the URL that you use as your entry point to SugarCRM, ending with “index.php”.

When using LDAP authentication, SugarCRM requires that the password is sent as plain text. If you want that to happen, you will have to check the option “Send password in plain text instead of the MD5 hash”.

Contact Lookup

You can change the maximum digit length to compare in the Contact Lookup section. When an inbound call arrives into your extension, the caller ID may have different formats depending on your PSTN or VoIP Provider. The ID could have an international format (including the country code), national format (including the region or city code), or local format (including only the local number).

Also, you may have created your Contact’s phone details in SugarCRM with prefixes that are not present in the caller ID, such as mobile phone prefixes. In order to match the caller ID with the contact’s phone in these cases, you need to specify this parameter. The system will compare the last number of digits of the caller ID with the last number of digits of your contact’s phone, where the number of digits is the specified maximum digit length to compare. Usually this parameter should be the length of your local number. With a higher number, you get more accuracy, but you may possibly not match the caller ID with some contact. With a lower number you get less accuracy (with possible false positives), minimizing the possibility of a no match.

You can choose to look for contact information in the Contacts, Leads and / or Accounts tables, and select the lookup order in these tables.

If you need to automatically open a new call log in SugarCRM when a contact is matched, i.e. when the call starts, just check that option. If this option is cleared and the “Store Call Information in SugarCRM” is checked, the new call log record will be shown after the call has finished and the call duration will be pre-populated.

Finally, you may configure a specific browser to use when opening contact records, or use the default one.

Create Contact

When you receive an inbound call from a new contact, which is not found in SugarCRM, you have the option to create it. In that case, you need to fill in a form with the contact’s information. That form contains the first name, the last name, the company name, the job title, the e-mail and the address. With the “Field mapping” section you can customize what SugarCRM fields are used to store each field from the create contact tab.

For example, by default the Company field from the create contact tab is stored into the SugarCRM “account_name” field. You could change that and store that information into the SugarCRM “department” field.

The drop down box on the middle of each row contains the list of valid fields for a SugarCRM contact, adding a final option “custom field”. When you select “custom field”, the text area on the right is automatically enabled and you can enter there the name of a custom field that you may want to use. This way you can also use your customizations.

Once the contact has been created, you can decide if it must be opened in SugarCRM. This may be useful for example when you need to add some additional information to the recently created contact.

Trial and Registration

The first time you enable the SugarCRM plugin, a 30 days trial will be automatically started. You will be able to use the full functionality during the trial period. When the trial expires, you need to activate a license key to continue using the SugarCRM integration. The Register button allows you to enter the product key purchased.

Inbound Call Behavior

When an inbound call arrives to your extension and a contact is matched, depending on your 3CX CRM Integration module configuration, the contact record will be automatically shown in your selected browser, or you will be able to click a link to open it. Also, if you have the option “Open new call log in SugarCRM when a contact is matched” checked, a new call log record may be automatically shown and opened in SugarCRM.

If you have the option “Store Call Information in SugarCRM” checked, when the call ends, and the option “Open new call log in SugarCRM when a contact is matched” cleared, a new call log will be created and automatically opened in the selected browser.

If you have configured the plugin to open a new call log when the call starts or ends, you will be able to fill the desired call information and comments directly in SugarCRM, or even cancel the call log and do not save it at all.

If a contact is not matched on an inbound call, clicking on the “Create contact” link in the screen pop-up will open the create contact tab. You can fill in that form and automatically create the contact in SugarCRM, using the field mapping configured in the “Create Contact” tab, and optionally opening the contact created using your selected browser.

Launching Calls from SugarCRM

Adding Customizations

IMPORTANT NOTE: the following procedure will override the customizations on your SugarCRM installation. If you have customized your SugarCRM installation, be aware that existing customizations WILL BE LOST. In that case you have two possible paths to follow:

1)      Install the provided customizations and then make your customizations again.

2)      Don’t install the provided customizations, add them manually instead.

In order to install the customizations:

1. Login to SugarCRM, and go to the “Administration” page.
2. Under the “Developer Tools” section, select “Module Loader”.
3. Click the “Browse” button and find the customizations file located in the installation directory, for example, “C:\Program Files\3CX CRM Integration\3CX SugarCRM plugin package.zip”, and press the “Upload” button.
4. The package “3CX SugarCRM plugin package” will be listed. Press the “Install” button. You will be requested to accept the license terms. Then press the “Commit” button.
5. You should see the “Module Installed Successfully” message.

If you need to make the customizations manually:

1. Login to SugarCRM, and go to the “Administration” page.
2. Under the “Developer Tools” section, select “Studio”.
3. Click on “Contacts”. Then click on “Fields”.
4. Add a new field “Call work”. Select “Data”, “Field”, “Display Label=Call work with 3CX”, “System Label=LBL_CALL_WORK”, “Help Text=Some help text”, “Comment Text=Some comment text”, check the “Generate URL” option, “Default Value= http://localhost:5536?type=contact&phone_type=phone_work&id={id}”, “Max Size=255”, “Open link in=New Window”.
5. Add a new field “Call assistant”. Select “Data”, “Field”, “Display Label=Call assistant with 3CX”, “System Label=LBL_CALL_ASSISTANT”, “Help Text=Some help text”, “Comment Text=Some comment text”, check the “Generate URL” option, “Default Value= http://localhost:5536?type=contact&phone_type=assistant_phone&id={id}”, “Max Size=255”, “Open link in=New Window”.
6. Add a new field “Call fax”. Select “Data”, “Field”, “Display Label=Call fax with 3CX”, “System Label=LBL_CALL_FAX”, “Help Text=Some help text”, “Comment Text=Some comment text”, check the “Generate URL” option, “Default Value= http://localhost:5536?type=contact&phone_type=phone_fax&id={id}”, “Max Size=255”, “Open link in=New Window”.
7. Add a new field “Call mobile”. Select “Data”, “Field”, “Display Label=Call mobile with 3CX”, “System Label=LBL_CALL_MOBILE”, “Help Text=Some help text”, “Comment Text=Some comment text”, check the “Generate URL” option, “Default Value= http://localhost:5536?type=contact&phone_type=phone_mobile&id={id}”, “Max Size=255”, “Open link in=New Window”.
8. Add a new field “Call other”. Select “Data”, “Field”, “Display Label=Call other with 3CX”, “System Label=LBL_CALL_OTHER”, “Help Text=Some help text”, “Comment Text=Some comment text”, check the “Generate URL” option, “Default Value= http://localhost:5536?type=contact&phone_type=phone_other&id={id}”, “Max Size=255”, “Open link in=New Window”.
9. Add a new field “Call home”. Select “Data”, “Field”, “Display Label=Call home with 3CX”, “System Label=LBL_CALL_HOME”, “Help Text=Some help text”, “Comment Text=Some comment text”, check the “Generate URL” option, “Default Value= http://localhost:5536?type=contact&phone_type=phone_home&id={id}”, “Max Size=255”, “Open link in=New Window”.
10. Now go back to “Contacts”. Click on “Layouts”. Select “Detail View”. Add a new panel named “Call with 3CX”. Then add the 6 fields created above into the new panel. Save & Deploy.
11. Repeat the previous steps for Leads and Accounts.

Launching Calls from the SugarCRM Web Interface

Once you have imported the customizations provided by this plugin (or created them manually), you will see a new panel in the detail view for contacts, leads and accounts, containing links to launch outbound calls to any phone number using 3CX Phone System, as shown in the following screenshot.

When you click for example “Call with 3CX” -> “Call mobile with 3CX”, the call to the contact’s mobile phone will be launched using the 3CX MyPhone application, which must be running. If the application is not running, you will receive a message with the error description.

Troubleshooting

Changing the Outbound Call Receiver Port

In order to allow automatic dialing of outbound calls from the SugarCRM web interface, you need to add some customizations. Those customizations contain hyperlinks to the outbound call receiver included in this plugin. The outbound call receiver listens by default in port 5536.

If another application in your computer is using that port number, you will see an error message when the SugarCRM plugin starts, indicating that the port is in use by another application.

We recommend that you reconfigure the conflicting application to use another port number. If you can’t do it, you will need to change the configuration of this plugin for every computer using the plugin within your company and the customizations provided by this plugin.

In order to change the port number, do the following:

1. Unzip the “3CX SugarCRM plugin package.zip” file located in the installation directory, for example “C:\Program Files\3CX CRM Integration\3CX SugarCRM plugin package.zip”.
2. Open the manifest.php file with a text editor, and change the port number 5536 with the new port number you want to use. To locate the port number, look for the text “http://localhost:5536”.
3. Zip everything again into the same file name.
4. Import customizations as described in the “Launching calls from SugarCRM” section.
5. Open the configuration file located in “%AppData%\3CX CRM Integration\3CX CRM Integration.ini” and change the parameter “OutboundCallsPort” in section “SugarCRM Plugin”. Ensure that the new port number is not being used in every computer that needs to run this plugin in your company.
6. Repeat the previous step in every computer that needs to run this plugin in your company.