How to Integrate your Drupal Website with Salesforce CRM

Recently, I wrote a blog post on the benefits of integrating your website and CRM, and Anthony followed up with another on the typical integration patterns you commonly see. Annertech have a lot of experience integrating Drupal websites with various CRMs, so this is the start of a new series on CRM integration where we will go into more detail on some of the more popular CRMs we’ve worked with. First up: Salesforce!

I first started integrating Drupal with Salesforce back in 2009 with Drupal 6 for Trócaire. Since then we’ve worked with it multiple times with both ‘web-to-lead’ integration and ‘two-way synchronisation’ integration, with both Drupal 6 and 7.

With ‘web-to-lead’ integration, the website acts as a data capture mechanism, generating leads for Salesforce. When a user submits a form on the website, the data is instantly sent to Salesforce and a 'lead' object is created. Whereas with the two-way ’synchronisation’ integration option, Salesforce remains the canonical data source, but the website can update Salesforce with the latest data captured, and can also pull down the latest updates from Salesforce to ensure the user always sees the latest version of the data. This is normally used in the case of managing membership details - so members can view and update their contact information online while administrators can modify them via Salesforce UI and both systems have the latest copy of the data.

SOAP vs REST

When we worked on our first Drupal-Salesforce integration in 2009, there was only a SOAP interface available when communicating with Salesforce. Since then they have brought in a REST interface, which offers some benefits over SOAP including the fact that it is  faster, more efficient and easier to integrate with.

Entities

The module landscape has also changed with Drupal 7. The powerful Salesforce Suite is still the go-to module for any Drupal-Salesforce integration but it changed drastically between Drupal 6 and 7. The main change is that it is now entirely entity driven. This means it will only create or update records in Salesforce when an entity is created or updated. This is great for updating Salesforce with new users, new commerce shop orders, or any other Drupal entity you may have on your site. However, this means that webforms submissions are not supported, which I’ll discuss in more detail shortly.

Salesforce Suite provides a number of hooks you can leverage to manipulate the data before it gets sent/received, as well as hooks for altering the mappings and other useful integration points. The main one we availed of was hook_salesforce_push_params_alter() which allows you to alter the data that gets sent and add additional mappings. I found this one particularly useful for conditional mappings - e.g. if the data that gets sent for a mapping varies based on the data entered or a combination of values entered.

Salesforce Suite supports both push and pull integration, so it is suitable for web-to-lead and two-way synchronisation. In such instances, the module will pull down the latest version of the data from Salesforce. This pull operation is usually triggered in some form, for example a user goes to edit their profile, or renew their membership, etc. However, it could also be triggered on a periodic cron run. Whatever you use to trigger it, just be sure not to issue too many API calls as you’ll just slow down the site and probably upset the folks at Salesforce! Once triggered, the associated entity is updated with the newly fetched data.

Webforms

The reliance of the Salesforce Suite module on entities posed a number of problems for us however. Most sites we create have a number of webforms, from lead generation forms to ‘volunteer with us’ type forms and donation forms. For new sites, there is an alternative to the webforms module: Entity Form. With the Entity forms module, every time the form is submitted a new entityform submission entity is created. As it’s an entity, there is no problem using the Salesforce Suite module to send the submitted data to Salesforce.

However, it’s not always feasible to use the Entity Form module. This was the case for us where we had an existing site with a large number of webforms already in place, including one that used the Pay module for processing donations. Instead we opted to use the Salesforce Webform Data Integration module. Unfortunately this doesn’t integrate with Salesforce Suite and uses the old SOAP interface, so you will have to configuration the Salesforce credentials twice and in potentially two different ways. There is a patch in the issue queue which integrates the two modules to avoid this issue, and there’s a few other patches from the issue queue that you will need too.

There is an older Salesforce Webform Integration module maintained by myself for Drupal 6, but it relied on the old non-entity driven Salesforce Suite architecture and so I’ve deprecated this in favour of Salesforce Webform Data Integration module. Other Salesforce-webform integration modules have been released since and have matured over the past couple of years that I have yet to try. Given the current lack of activity on the Salesforce Webform Data Integration module, these might be worth considering for newer projects, but Salesforce Webform Data Integration is still the one most actively in use. There’s a good comparison of these quite similar modules on drupal.org which is worth a look before choosing which module to use for your project.

However, one of the nice features about the Salesforce Webform Data Integration module is the ability to configure, on a per-form basis, whether that form should send data to Salesforce and then on a per-field basis configure which fields in Salesforce the data should be mapped to. We found this particularly useful when the client wanted to be able to create new forms and manage the mappings themselves without having to come back to the developers.

As this module works with webform submissions, and not with entities, it only supports web-to-lead integration. If the data in Salesforce is updated, there is no way to update the website with the latest changes.

It also provides a number of hooks including hook_salesforcewebform_data_alter(), which similarly to the Salesforce Suite module hook, allows you to manipulate the data before sending it to Salesforce, for example, we had to change the single on/off checkbox values from 1 and 0 to TRUE and FALSE.

Resilience

One of the features all of the Salesforce modules seem to be lacking, and most external-CRM integration modules for that matter, is the ability to record which transactions have made it through to the CRM successfully.

On all external CRM integrations we’ve had to implement, I think we’ve had to maintain a custom logging mechanism to track which submissions to Salesforce have made it through and which ones have failed, and if so, with what error. For example, sometimes submissions can fail to get through if there is a problem with the data (like the 1/0 vs TRUE/FALSE issue mentioned previously) or if there was a network issue that prevented it reaching Salesforce. To implement this functionality we were able to use hooks like hook_salesforcewebform_submission_pre_send() and hook_salesforcewebform_submission_post_send() to record submissions sent to Salesforce, and then update their status afterwards.

We’ve also provided a user interface for the client to find submissions that failed, and they can either force it to reattempt the submission, or wait until it attempts it again on the next cron run.

So, that's a short introduction to some of the technical side of implementing your Drupal website with a Salesforce CRM. If you think your organisation could benefit from some of our knowledge in this area, why not give us a call on 01 524 0312 or drop us an email at hello@annertech.com.