Authored by Drupal Geeks on 14 Oct 2021

Here at Drupal Geeks, we are frequently asked to do integrations with Drupal and Since it is a popular request and a very useful integration, we thought we’d share some of the basics involved with the technical execution of these integrations. Prepare yourself because we are about to geek out!


To begin with, we’d like to share with you some basic information about both the Drupal CMS platform and Salesforce Suite. This will help paint a picture of their attributes and illustrate the business problems we solve for our clients.

Drupal provides a solid and flexible platform for integrating a wide variety of services and capabilities for your online presence. Since Drupal is an Open Source Content Management System (CMS), it can be customized to meet almost any integration need.

By providing a solid architecture and Application Programming Interface (API) system, Drupal allows experienced developers to create custom extensions to the system, called “modules,” based on your specific business needs.

A common need for many organizations is integrating the Drupal platform with, the powerful Customer Relationship Management (CRM) tool that includes pre-built applications for orchestrating business relationships between clients, leads, and contacts. is a leader in cloud computing systems for CRM, sales, social, call center, knowledge management software, and cloud computing. Customer relationship management (CRM) focuses on your enterprise's number one priority— more closed business. The CRM tool accomplishes this by tracking lead generation efforts, sales pipeline management, and enables the necessary functions for successful sales execution and customer service.

Drupal CMS provides a popular and useful module called Salesforce Suite that is a collection of modules working in concert to provide a robust integration between Drupal entities (nodes, users, etc.) and Salesforce data objects (Accounts, Contacts, Opportunities, etc.). It supports pushing Drupal data to Salesforce as well as pulling, or importing, Salesforce data into Drupal. Changes can be made in real time or asynchronously in batches during cron run. There are many advantages of using this module for those who use both Drupal and

The Salesforce Suite modules operate independently of each other and have one central ‘Salesforce API’ module acting as a gateway to the remote Salesforce operations. Additionally, the ‘Salesforce API’ module provides an administration screen to create object mapping between Drupal and Salesforce. The remaining modules use the ‘Salesforce API’ module’s features to save data from Salesforce objects to their corresponding Drupal counterparts and vice versa. The modular structure allows developers to extend existing integration functionality and also create new integration for unique business specific Drupal entities.

Modules of the Salesforce Suite are:

1 - Salesforce (salesforce): This module provides OAUTH2 authorization and a wrapper around the Salesforce REST API. 2 - Salesforce Mapping (salesforce_mapping): This module maps Drupal entities to Salesforce fields including field level mapping. 3 - Salesforce Push (salesforce_push): The Push Drupal entity enables updates into the Salesforce CRM tool. 4 - Salesforce Pull (salesforce_pull): This module pulls Salesforce object updates into Drupal on cron run. (Salesforce outbound notifications are not supported.) 5 - Salesforce Soap (salesforce_soap): This is a lightweight wrapper around the SOAP API, using the OAUTH access token to fill in functional gaps missing in the REST API. This module requires the Salesforce PHP Toolkit.

By default, the Salesforce suite supports one-to-one mapping that means mapping can be possible with one Drupal entity type to one Salesforce object type at a time. To be more specific, this means that the user entity to lead object mapping is possible, however mapping Drupal user entities to Salesforce lead, account, and contact objects are not possible. To achieve one-to-many mapping we coded wrapper modules with Salesforce lead object conversion features, batch processed the existing entities in Drupal to Salesforce, and utilized dynamic record types for Salesforce, custom objects, and more.

Basic Implementation:

Data objects of both Drupal entities and Salesforce objects can be synchronized with the help of their unique IDs which are stored in the Drupal database.

Mapping data structure objects and fields can be accomplished through using wsdl files that expose the Salesforce architecture to Drupal. This facilitates the means to effectively communicate field data between the two endpoints.

Mapping objects are manually created at the Drupal backend of the Salesforce Suite administrator’s mapping page. A mapping object can be created for each Drupal entity involving field level mappings. The field level mappings allow proper communication between the two endpoints.

Using the same kind of workflow between the two endpoints, Drupal implements three basic operations - Create, update, and delete. When an operation occurs, e.g., creating a node, Drupal makes the corresponding call to Salesforce. Each operation has its own subtle difference:

Create – Drupal creates the entity locally, creates corresponding objects on Salesforce, then saves the local entity node, and the remote Salesforce ID to the Salesforce Suite’s object mapping table.

Update – After updating the entity locally, Drupal looks up the corresponding Salesforce object from the object-mapping table. Using the Salesforce ID, Drupal calls for Salesforce to update its record using the updated data from Drupal.

Delete – The delete operation is similar to the create operation with the exception that Salesforce will delete its record, and the entry from the object-mapping table is also removed.

With the basic setup of the Salesforce Suite module, we can create mappings between Drupal entities and Salesforce objects at field level. Mapping examples are:

1 - Drupal entity (Investment Opportunity) to Salesforce custom object (RMIO) which could be a uni-directional synchronization (Drupal to Salesforce) and the entity syncs only on the Drupal entities create and update actions.

2 - Drupal User to Salesforce Lead which could be a bi-directional synchronization (both Drupal-to-Salesforce and Salesforce-to-Drupal) and the entity syncs only on the Drupal entities create and update and Salesforce object update actions.

2.1 - Complexity of this mapping involves a Drupal entity update action and should not be triggered after the user entity of Salesforce lead object has been converted into Salesforce account and contact objects.

3 - Drupal User to Salesforce Account which could be a bi-directional synchronization (both Drupal-to-Salesforce and Salesforce-to-Drupal) and the entities sync only on the Drupal entity update and Salesforce object update actions.

4 - Drupal User to Salesforce Contact that can be a bi-directional synchronization (both Drupal-to-Salesforce and Salesforce-to-Drupal) and the entity sync only on the Drupal entity updates and Salesforce object update actions.

4.1 - Complexity of mapping (eg- 3 and 4) involves, Drupal entity updates that should not be triggered before the user entity of Salesforce lead object gets converted into a Salesforce account with contacts. Prior to lead conversion, there are no account and contact objects available for Salesforce leads.

4.2 - Mapping the same Drupal user entity to different Salesforce objects (Leads, Accounts, Contacts). This module supports creating mapping for the same Drupal entity type to different Salesforce object types. It should sync to all mapping at a time in different cases, but it can only sync one Salesforce object type at a time.

5 - Drupal entity (Investment) to Salesforce Opportunity which could be a uni-directional synchronization (Drupal-to-Salesforce) and the entity sync only on the Drupal entity create and Drupal entity update actions.

5.1 - Complexity of mapping involving the Drupal entity create entails checking whether the logged in user entity of a Salesforce lead is converted or not. If converted, create a new opportunity in Salesforce using the Drupal entity data. If not converted, do a lead conversion that involves of converting the lead into account and contact objects then with the help of an account ID and mapped Drupal entity data, and a new opportunity is created in Salesforce.

Other features that are not in the Salesforce Suite are:

1 - Dynamic record types for the Salesforce objects based on the entity field value.

2 - Batch process for the existing Drupal entities are user, node entities, and lead conversion process.

Business Solutions:

When our clients come to us with this particular integration issue, there are two business problems we hear about consistently. The first is that they want to create a specific workflow that maps to their Drupal forms, and secondly there is a strong need for automated tasks. Our drupal development team customizes a unique solution for every client to help with these challenges and deliver complex functionality.

Often when we utilize Salesforce Suite modules and write a Wrapper module called Salesforce Alter (sf_alter) which covers all the complex functionality that are not available in the Salesforce Suite. This helps our clients to achieve get the customization they need for their workflow.

Modules used for of Salesforce Alter are:

1 - Salesforce Alter (sf_alter): This provides a solution to the lead conversion and the dynamic record type selection on each entity created.

2 - Salesforce Mapping Alter (sf_mapping_alter): This module maps Drupal entities to Salesforce fields, including one-to-many mapping at a time.

3 - Salesforce Push Alter (sf_push_alter): Push Drupal entity updates into Salesforce and skip some entity updates (EX:2.1, 4.1).

4 - Salesforce Pull Alter (sf_pull_alter): This module pulls Salesforce object updates into Drupal for one-to-many mappings.

5 - Salesforce Push Batch Initiate (sf_push_batch): This module enables a Drupal batch process for existing entities to Salesforce (user to lead mapping, node entity mapping and Salesforce lead conversion).

After we have implemented solutions to our clients’ satisfaction we keep in touch with them to assess how the work we have provided impacts their business. We have found that with a custom integration in place for Drupal and our clients experience a more efficient workflow, and save countless hours utilizing a more highly productive system.

Can we help you solve similar challenges, or do you just need help understanding all of our geek speak? We are happy to have a conversation with you. Our team has the expertise and knowledge to assist you with the most technical to the most basic of questions regarding this and other topics. Give us a call at 312-340-7112, or e-mail us at [email protected]

References: 1 - 2 - 3 - 4 - 5 -