- Products
- Solutions
- Developers
- Support
- About
SugarCRM is a powerful and extensible CRM platform. Its functionality includes marketing campaigns, customer support, and sales force automation as well as providing mobile and cloud based CRM capabilities for folks on the go. Another great thing that Service Objects loves about SugarCRM is the ability to quickly and easily deploy automated processes that can call some of our data validation APIs to boost SugarCRM’s effectiveness, and help reduce waste and fight fraud through our APIs.
This guide will serve as a quick integration guide to show you how to get a logic hook that calls our DOTS Address Validation – US service up and running in no time!
Prerequisites
To follow along with this tutorial, you’ll need the following:
For this specific example, we’ll create an installable package for a logic hook that can be easily added and enabled in your Sugar CRM instance. If you are not familiar with logic hooks, we’d recommend reading up on them along with some other documentation that SugarCRM provides for creating an installable package.
For this tutorial, we are going to take the example installable package listed on the SugarCRM documentation page and adapt it for our use case and needs. Specifically, we’ll be targeting the “Contacts” module in our example, so we’ll need to update the file paths and class names in the example logic hook package. For reference, here is our file structure:
The file paths, object, and function names will need to be updated in the manifest.php and contact_address_hook.php file to point towards the updated files, classes and functions that will make the actual call to our Address Validation – US API. If these values are not set correctly, you will run into errors when you attempt to install the logic hook in your SugarCRM instance. Here is the installation information in our contact_address_hook.php file:
And the $installdefs value in our manifest.php file:
Take note of the file, class and function values in the above image. These will tell SugarCRM in what module to install this logic hook and what function to call. As noted above, we’ll also be using the ‘before_save‘ trigger so that an address will be automatically updated when a user clicks the Save button when updating a contact.
Now that we have all the prerequisites set up, we’ll take a look at the contacts_save.php that will hold the code that will actually call our service.
The contacts_save.php file will contain the following class definition and functions:
The GetBestMatches and the callURL functions were taken directly from our PHP class library. Our developer guides will highlight how to use them. Since that code is available for download, we won’t go into detail as to what the actual calls to our webservice look like. But in short, these class libraries use our recommended best practices in calling our web services. Namely, they automagically integrate failover calls to our backup datacenter in the event that the primary datacenter experiences an issue. This failover helps ensure uptime and provides added assurance that you can get your data validated in the event that the primary Service Objects datacenter isn’t reachable. These class libraries also work with Service Objects production and trial license keys. Here’s a screenshot of the failover in place:
Now that we have that in place, let’s take a look at the function that the logic hook will eventually call.
For starters, we’ll want to wrap this logic hook in a try/catch block and we’ll want to implement a check against some custom fields that we’ve created in SugarCRM for this example. We’ve added the fields address1, dpv and dpvdesc to the Contact module. We’ll access those fields in the $bean object with $bean->address1_c, $bean->dpv_c, and $bean->dpvdesc_c respectively.
In order to keep our calls to the service to a minimum, we’ll only call the service if the dpv_c field is empty and the address1_c field is not empty. This will help us ensure that we don’t call the service when it has already been called previously on a record. In other words, address1 and zip or city and state must be present in order to receive a valid response from the service. Your specific criteria for when to call the service may look different, but this would be the place to add it.
We’ll also check some config settings for values that we’ve added the config.php of our SugarCRM environment. Adding these values to your config setting can make the transition from a trial key to a production license key much simpler. Instead of having to redeploy a webhook with a hardcoded license key, we can dynamically pull down the trial or production license key based on the ‘callsoproductionendpoint‘ bool that we’ve put in the config.php file as shown below. We can then pass the appropriate license key and the bool into the GetBestMatches function we’ve implemented.
Now that we’ve set our license key and the bool that will decide whether or not we call the production endpoints, we’ll get into the rest of the code that will update our address fields with the validated information.
We’ll call the GetBestMatches operation and then we’ll check the response for an error. If no error was present, then our services returned a successful response and we can update the address fields of the $bean object along with our custom created dpv and dpvdesc fields.
If an error was returned, we’ll update the dpv field to highlight that an error occurred. And that’s all we need code-wise to make this logic hook work! Let’s move onto installing it into the SugarCRM instance.
To do this, you want to add the root Files folder along with the manifest.php file to a .zip file. If you are using a Windows machine, you can select both the Files folder and the manifest.php file and right-click and then select Send To Compressed (zipped) folder. Congrats! You now have a .zip folder that is ready to be installed into your SugarCRM instance.
To install, we can log into our SugarCRM instance as an admin and then navigate to the admin section. This should be under your profile avatar.
Once you’re in the admin section, navigate down to Module Loader.
Now select Choose File and navigate to the .zip file you just created, and then select Upload.
ow we can install the logic hook by selecting the Install button:
If everything went as planned, your logic hook should be ready to use!
To test, we’ll head over to the Contacts section of the CRM instance and edit the address of a contact. For reference, we’ve edited what fields show up on our contact page to make the fields we’re interested in updating stand out.
We’ll enter in the following address information for our Application Engineer entry and we’ll hit save.
And now we should have some USPS standardized address data as shown below:
Feel free to download the .zip file we created for this here.
© 2024 Service Objects, Inc. All rights reserved.
