Check for existing duplicates on object-create

Dependency Warnings

The sf_prematch module assumes that the patch found at http://drupal.org/node/506032 has been installed.

Although it doesn't require it, the sf_prematch module also implements the hook found at http://drupal.org/node/506012 Without that patch, rows will not be deleted from sf_prematch's database table, even if they are no longer needed.

Use case addressed by this patch

Corresponding objects are created in salesforce and Drupal: e.g. the same contact is created in both. Since these objects are independently created, there is no syncing relationship between them.

Current behavior addressed by this patch

When the Drupal object is exported, a new salesforce object is created for it to sync with. This means that there are now two corresponding salesforce objects for the one Drupal object, and that only the new salesforce object is in a synchronization relationship with the Drupal object.

Desired behavior achieved by this patch

Before creating a new salesforce object, attempt to find an already-existing salesforce object which corresponds to the Drupal object that is in the process of being exported. If a match is found, do not create a new salesforce object, but instead export to the found one, and create a synchronization relationship between the two objects.

The way it attempts to match is by looking for a salesforce object of the correct type where the value of some field(s) matches that of the Drupal object which is being exported.

Administrators are given the ability to choose one to three fields to use in matching, and to choose the logic for applying those fields.

Currently, the logic field is redundant. However, I anticipate the options for logic getting more sophisticated in future.

What the patch does

Add hook_sf_find_match

When a module is exporting a Drupal object, and that object does not yet have a corresponding salesforce object, the exporting module calls this hook to give other modules a chance to find a matching salesforce object. The patch modifies sf_node and sf_user so they call this hook when they are exporting an object that has no assigned sfid.

Note that the hook expects the first argument to be the action that is being taken: i.e. export or import. The current patch only deals with exporting, but there is no reason that future modifications could not implement matching on import (or other actions should some arise).

A new module

This patch includes sf_prematch, a new module specifically for the purpose outlined above. It implements hook_sf_find_match.

It also provides the administrative interface outlined above, and a new permission to control which roles can use that interface.

I implemented this is a module for two reasons.

Doing so allowed me to minimize the extent to which modifications were needed in the existing code, and this approach allows the possibility of other modules which might implement the new hook differently. Basically, although it seems to me that the functionality provided here might well belong in core, I could see other people thinking differently, and I could see people wanting similar but somewhat different functionality. A new module seemed like the best way to address all of that.

Why two patches?

Although it seems to me that it makes sense to include the new module as part of the general salesforce distribution, I am open to being told otherwise. Thus I have included two versions of the patch. One version includes the module, and the addition of the hook to sf_user and sf_node. The other version includes only the changes to sf_user and sf_node, but not the new module. If it seems preferable to make the new module a separate project, I am open to doing that.