Object Sync for Salesforce

Description

This plugin maps and syncs data between Salesforce objects and WordPress content types. For any supported WordPress content types (e.g. post, page, user, or any custom content type in your installation), you can assign Salesforce objects that will be created / updated / deleted when the data in WordPress is saved, and the WordPress objects can be created / updated / deleted when the data in Salesforce is saved.

Both of these directions act upon any matching data that is created after the plugin is installed. For each such assignment, you choose which WordPress and Salesforce fields should be mapped to one another.

This plugin also includes developer hooks that allow for additional plugins to modify what data the plugin is working with, or what happens upon specific events.

Installation

WordPress

Prerequisites

To install the plugin in WordPress, your PHP environment needs the following:

  1. At least version 5.5.
  2. SSL support (this is required to connect to Salesforce).
  3. A domain where WordPress is successfully running. For purposes of this documentation, we’ll assume that you are using https://<your site>. You would use https://www.example.com instead, if your site was www.example.com.

Activate the plugin

In the Plugins list in WordPress, activate the plugin and find the settings link (you can also find this plugin’s settings in the main Settings list in WordPress, under the Salesforce menu item once it is activated).

The plugin’s settings URL is https://<your site>/wp-admin/options-general.php?page=object-sync-salesforce-admin.

Salesforce

Prerequisites

You’ll need to have access to a Salesforce developer account. This should come with Enterprise Edition, Unlimited Edition, or Performance Edition. Developers can register for a free Developer Edition account at https://developer.salesforce.com/signup.

We recommend using a Sandbox to set up this plugin first before running it in production.

For purposes of this documentation, we’ll assume that your name, as defined in Salesforce, is Your Name. This is what you see at the top right of the browser window, when you are logged in.

Create an App

  1. In Salesforce, go to Your Name > Setup. Then on the left sidebar, under App Setup, click Create > Apps. In the Connected Apps section of this page, click New to create a new app.
  2. Enable OAuth Settings
  3. Set the callback URL to: https://<your site>/wp-admin/options-general.php?page=object-sync-salesforce-admin&tab=authorize (must use HTTPS).
  4. Select at least “Perform requests on your behalf at any time” for OAuth Scope as well as the appropriate other scopes for your application. Many setups will also need to select “Access and manage your data (api)” as one of these scopes.

Get the values for WordPress

After you save these settings, click Continue and you’ll see the values for your new app. For WordPress, you’ll need these values:

  1. Consumer Key (in the screenshot, this value says “valuefromsalesforce”)
  2. Consumer Secret (you’ll have to click “Click to reveal” to get this value)

Connect the plugin to Salesforce

Settings

Go to the Settings tab for the plugin. It is the default URL that opens when you click Salesforce in the main Settings menu. Enter the values based on your Salesforce environment.

  1. Consumer Key: (your value from above)
  2. Consumer Secret: (your value from above)
  3. Callback URL: https://<your site>/wp-admin/options-general.php?page=object-sync-salesforce-admin&tab=authorize
  4. Login Base URL: For most Salesforce environments, you can use https://test.salesforce.com for sandbox, and https://login.salesforce.com for production.
  5. Authorize URL Path: The plugin starts with a default of /services/oauth2/authorize. You should generally not have to change this.
  6. Token URL Path: The plugin starts with a default of /services/oauth2/token. You should generally not have to change this.
  7. Salesforce API Version: You should generally use the latest version your install has access to. This plugin starts with 42.0, but once it is authenticated the text field will be replaced with a dropdown of your available versions from which you can choose.
  8. Limit Salesforce Objects: These allow you to indicate whether Salesforce should relate to objects that can’t be triggered or updated via the API. Generally it’s a good idea to have these boxes checked to avoid errors.
  9. Salesforce Field Display Value: When mapping Salesforce fields, you can choose whether the plugin will display a field’s Field Label (possibly a more user friendly value) or the API Name (which is always unique). Neither choice changes how the plugin functions on the back end, but making a choice can sometimes make the mapping choices easier to find.
  10. Pull Throttle (seconds): This plugin starts with 5 seconds, but you can change it based on your server’s needs.
  11. Debug mode: This won’t do anything until after the plugin has been authorized, but once it has you can use it to see more information about what the API is doing. Don’t check this in a production environment.

Save the settings. If the values required are set, you’ll see a message that says “Salesforce needs to be authorized to connect to this website. Use the Authorize tab to connect.” You can use that link for the next steps.

Using constants for settings

You can set several of the above values as constants in your wp-config.php file. The plugin will always use a constant ahead of a database setting.

Supported constant names are:

  1. OBJECT_SYNC_SF_SALESFORCE_CONSUMER_KEY
  2. OBJECT_SYNC_SF_SALESFORCE_CONSUMER_SECRET
  3. OBJECT_SYNC_SF_SALESFORCE_CALLBACK_URL
  4. OBJECT_SYNC_SF_SALESFORCE_LOGIN_BASE_URL
  5. OBJECT_SYNC_SF_SALESFORCE_AUTHORIZE_URL_PATH
  6. OBJECT_SYNC_SF_SALESFORCE_TOKEN_URL_PATH
  7. OBJECT_SYNC_SF_SALESFORCE_API_VERSION

Set them in wp-config.php like this:

define('OBJECT_SYNC_SF_SALESFORCE_CONSUMER_KEY', 'valuefromsalesforce');
define('OBJECT_SYNC_SF_SALESFORCE_CONSUMER_SECRET', 'valuefromsalesforce');
define('OBJECT_SYNC_SF_SALESFORCE_CALLBACK_URL', 'https://<your site>/wp-admin/options-general.php?page=object-sync-salesforce-admin&tab=authorize');
define('OBJECT_SYNC_SF_SALESFORCE_LOGIN_BASE_URL', 'https://test.salesforce.com');
define('OBJECT_SYNC_SF_SALESFORCE_API_VERSION', '40.0');
define('OBJECT_SYNC_SF_SALESFORCE_AUTHORIZE_URL_PATH', '/services/oauth2/authorize');
define('OBJECT_SYNC_SF_SALESFORCE_TOKEN_URL_PATH', '/services/oauth2/token');

For any value that is already defined in wp-config.php, the Settings screen will display “Defined in wp-config.php” in place of the text field.

Authorize

Go to the Authorize tab in the plugin’s settings. If it is not yet authorized, you’ll see a message that says “Salesforce needs to be authorized to connect to this website. Use the Authorize tab to connect.”

The authorize tab will force you to be logged in using HTTPS, if you weren’t already.

Steps:

  1. Click the Connect to Salesforce button to authenticate WordPress with your Salesforce installation.
  2. You may have to log into Salesforce.
  3. Salesforce will ask you to allow access to the app (in these instructions, the name is WordPress Example), and will show you what permissions it needs.
  4. Click Allow.
  5. You’ll be redirected back to WordPress. Don’t do anything until you see a message that says “Salesforce is successfully authenticated.”
  6. The tab will display a “Disconnect from Salesforce” button which you can click at any time, and will also show a bit of basic information about your Salesforce environment (the available API versions and a basic table of Contacts.)
  7. If you’d like to use a different Salesforce API version, go back to the Settings tab and pick your desired version from the dropdown.

More documentation

There is extensive documentation of the plugin, including its developer hooks, on GitHub. You can find a detailed initial setup instruction document there as well.

FAQ

Mapping custom fields

WordPress stores metadata as key/value pairs in its database. Many plugins and themes use this method to store custom field data. Object Sync for Salesforce supports mapping these fields (many other plugins use non-standard methods, and this plugin may or may not support them).

There’s a helpful spreadsheet (we are not affiliated with it, we just think it’s useful) comparing various options for custom fields you can review. If the plugin you wish to use uses Meta-based Storage (listed in the spreadsheet), you should be able to use it with Object Sync for Salesforce, but how well they work together will vary. Plugins with full meta compatibility (also listed in the spreadsheet) may work the best, but you don’t have to restrict yourself to those.

Object Sync for Salesforce, however, cannot see meta fields before the field has at least one value in the database. For example, if you have a “testfield” on your user object, it won’t be in the fieldmap options until there is at least one user that has a value for the field.

If you load Object Sync for Salesforce and then store data for a new meta field after this load, make sure you click the “Clear the plugin cache” link on the Fieldmaps tab.

Using with ACF (Advanced Custom Fields)

Object Sync for Salesforce does not and will not “officially” support ACF because you don’t have to use ACF to use WordPress or to use Salesforce. However, they are generally usable together.

Things to know:

  1. See the answer above about custom fields. Any ACF field must have at least one value in the database before Object Sync for Salesforce can map it.
  2. When you try to map an ACF field, you’ll see one that has an underscore in front of it, and one that does not. This is because ACF uses both for its own purposes. As long as you map the ACF field that does not have the underscore in front of it, you should be able to get data to and from Salesforce. For example, you could map a test_field to a Contact_description field. The fieldmap screen will show a _test_field in the dropdown, but you should be able to safely ignore that, and only map test_field.

While we will not include code that only runs for ACF in this plugin, we would happily point to any add-on plugin that uses Object Sync for Salesforce hooks to build a more comprehensive integration with ACF for all users who install this plugin while they’re running ACF.

Using with WooCommerce

Object Sync for Salesforce doesn’t have, and will not have, intentional support for WooCommerce. It kind of supports it, to the extent that WooCommerce uses WordPress’ default ways of creating objects and data. WooCommerce is very complicated, and on top of that it often deviates from those default WordPress methods, and it’s certainly possible that this plugin won’t support it when it does.

This doesn’t mean you can’t use them together, but it does mean this plugin is not intentionally built for that purpose. Because WooCommerce is not a requirement to use WordPress, or to use Salesforce, it will never be built directly into Object Sync for Salesforce.

Object Sync for Salesforce does have abundant developer hooks, and WooCommerce has its own API, and it would be possible to build an add-on plugin to provide full support by integrating these (we would happily point to it for all users who install this plugin while they’re running WooCommerce).

Troubleshooting

If you are successfully authenticated with Salesforce, but you have a fieldmap that is not passing data, there are several ways to troubleshoot. More information may be available in the plugin documentation.

Plugin configuration

  • Remember to clear the plugin cache on the Fieldmaps screen.
  • If you are not able to push data to Salesforce, try with asynchronous checked, and without. This will tell you if your issue is related to the plugin’s cron jobs.
  • To inspect your cron jobs, use the WP Crontrol plugin. Make sure the Salesforce push and/or pull jobs are running as you expect them to, and make sure to check the Schedule screen to make sure the jobs are scheduled as they should be.

Plugin logs

  • Make sure to use the Log Settings screen to configure logs. Once enabled, they are added to a custom post type called Logs in the WordPress menu.
  • If the plugin tries to create or update data, but WordPress or Salesforce encounter errors, the plugin will always try to create a log entry. If you see entries, review the title and content of each.

Plugin mapping errors

  • If the plugin fails in the middle of creating a map between two objects, a row may be created on the Mapping Errors screen. If it is a push error, it will tell you the WordPress object ID it was trying to map. If it is a pull error, it will tell you the Salesforce ID. You should not leave these entries.

Server logs

  • If you don’t see any error logs in WordPress, it is always a good idea to check your server’s error logs and see if PHP is encountering errors.
Plugin documentation

There is extensive documentation of this plugin, including its developer hooks, on GitHub.

Finding other options

This plugin can be relatively complicated, and sometimes other plugins can effectively integrate Salesforce and WordPress, especially if there are more limited, specific requirements. If one of these can meet those requirements, use it. We’re happy to link to additional choices here, as well.

  • WordPress-to-Lead for Salesforce CRM can be installed through the Salesforce AppExchange. It allows you to run a contact form which users on your WordPress site can submit, and the results are added to Salesforce as a Lead object.
  • Brilliant Web-to-Lead for Salesforce can be installed through the WordPress plugin directory. This is rather similar to the first option, but is a bit more customizable. By customizable, you can select the fields in WordPress and theme it in your WordPress theme.
  • Gravity Forms Salesforce Add-on can be installed through the WordPress plugin directory. It is quite powerful, as it can send form submissions from your WordPress site to Salesforce as whatever object you need. It’s important to mention that this works for any form created with the Gravity Forms plugin. It’s also important to mention that this does not sync data back from Salesforce into WordPress.
  • Third party integration apps such as Zapier are subscription-based, paid ways to integrate different systems, and they offer differing amounts of customizability. They will usually sync in both directions, so in this case from WordPress to Salesforce and vice versa. The only limitations of something like this are the cost over time, and the possible vulnerability of basing an integration on a third party that could, at some point, go away.
  • Visualforce If you are or have a Salesforce developer, you can build MVC based applications that integrate with Salesforce. It would be possible to build a system that uses, for example, the WordPress REST API to send and receive data to and from WordPress. This could be, in many ways, the flip side of what our plugin here does, but the complexity would be the same if the scope was the same.
  • Build other integrations in WordPress this plugin focuses on the Salesforce REST API, as it covers the integration needs we have. Salesforce also has many other developer options: the SOAP API (we hope to incorporate this into Object Sync for Salesforce at some point), the Bulk API, and the Metadata API. Developers could extend this plugin to integrate with one of these. We would welcome any pull requests!

Reviews

Everything you need to integrate SalesForce Objects with WordPress

A very complete plugin that contains all the functions to create and collect SalesForces objects from WordPress.

With a detailed and simple documentation this plugin helps like a charm in the development of applications and new functions.

It facilitates API authorization and is a very useful resource when integrating calls. Debugging, logging…

Just what we were looking for

We needed a way to keep Salesforce updated with new WordPress users as they signed up. This plugin was precisely what we were looking for! Had a minor snag with set up, but support (Johnathan to be specific) was right on the money diagnosing our issues.

5 stars for support alone! Thank you for making it easier to connect Salesforce to WordPress!

Great plugin and support

Super helpful plugin that makes Salesforce/Wordpress integrations feasible without custom development. The developer is super responsive, both in helping with configuration and addressing issues.

Excellent plugin, even better support

This plugin is great and was, in my opinion the best way to solve the problem I was working on without overkill. The plugin contributor is extremely quick to respond (even though the problem was not even caused by his work) and the support truly is excellent!

Well coded, well supported and works beautifully.

Used OSFS to pass data between a WooCommerce site and Salesforce. Discovered a small bug when testing on my staging site that was immediately (and I mean immediately) rectified by the devs. When I moved to the production site I ran into another small issue caused by the site’s transient feeds (not an issue with the plugin). Once again I hit the Support Forum and the devs helped me identify the problem.

The plugin works seamlessly and the support is top notch…better than most paid plugins I’ve used.

Read all 5 reviews

Contributors & Developers

“Object Sync for Salesforce” is open source software. The following people have contributed to this plugin.

Contributors

Changelog

  • 1.5.1 (2018-11-03)

    • New: update to version 2.1.1 of the ActionScheduler library.
    • Bug fix: when processing more than 2000 records, the offset and limit combination fails due to Salesforce API restrictions. In this release, the plugin changes the date parameter on the API query to the value for the last processed record.
  • 1.5.0 (2018-10-26)

    • New: the Mapping Errors tab supports deleting multiple error rows via checkboxes.
    • New: when caching API responses, the plugin caches the full array rather than the full array and the JSON data. This reduces the memory usage for object caches a little.
    • New: this plugin should be usable on WordPress VIP environments; it now checks for user_attributes instead of user_meta in those cases.
    • Bug fix: this plugin can now be properly deployed on hosts like Pantheon. Thanks to WordPress user @joepahl and GitHub user @BrianBenninger for reporting this.
    • Bug fix: when using meta fields for prematch, the plugin previously could fail to find a match even if the value existed. It now uses different matching for meta fields. This requires that users resave their fieldmaps, and also that we end support for WordPress 4.5.. Thanks to WordPress user @nodakjones for the bug report and testing assistance.
    • Bug fix: when using the ActionScheduler library, the plugin fails to process multiple rounds of pull requests. Now it uses the limit setting to page through all possible updated records. Thanks to WordPress user @jonsayer for the report and WordPress user @harmoney for help testing.
    • Developers: this release adds a new developer hook, object_sync_for_salesforce_pull_query_modify, which can modify the Salesforce API SOQL query before it pulls data from Salesforce. Thanks to WordPress user @yanlep for the suggestion.