findDuplicates()

The input is an array of sObject, each of which specifies the values to search for and the type of object that supplies the duplicate rules. The output identifies the detected duplicates for each object that supplies the duplicate rules. findDuplicates() applies the rules to the values to do the search. The output identifies the detected duplicates for each sObject.

Syntax

FindDuplicatesResult[] duplicateResults = 
    connection.findDuplicates(SObject[] inputSObjectArray);

Usage

Use findDuplicates() to apply duplicate rules associated with an object to values specified by each sObject. Each sObject also has a type that corresponds to an object.

findDuplicates() uses the duplicate rules for the object that has the same type as the sObject. For example, if the sObject type is Account, findDuplicates() uses the duplicate rules associated with the Account object.

For each input sObject, findDuplicates() adds a FindDuplicatesResult object to the output array.

The values specified in the sObject control matching. The values can include a record ID, a field map, or both. The specified values determine the behavior of findDuplicates():

Record ID only

findDuplicates() searches the object defined by the duplicate rule for an existing record that has the same ID. Then it loads the values from that record, and searches for duplicates based on those values.

Field Map only

findDuplicates() loads the values from the map and searches for duplicates based on those values.

Record ID and Field Map

findDuplicates() searches the object defined by the duplicate rule for an existing record that has the same ID. It loads any values from that record that aren’t specified in the map, and then loads values from the map. Based on the resulting union of values, findDuplicates() searches for duplicates.

The output of findDuplicates() is an array of FindDuplicatesResult objects with the same number of elements as the input array, and in the same order. The output objects encapsulate record IDs for duplicate records, if any. Optionally, the output objects also contain values from the duplicate records.

Each FindDuplicatesResult element contains a DuplicateResult object. If findDuplicates() doesn't find any duplicates for an sObject, the duplicateRule field in DuplicateResult contains the name of the duplicate rule that findDuplicates() applied, but the matchResults array is empty.

If the includeRecordDetails flag in DuplicateRuleHeader is set to false, findDuplicates() only returns the record IDs of the matching records. Otherwise, findDuplicates() returns all the fields specified in the primary CompactLayout associated with the target object.

Basic Steps for Use

1. Create one or more sObject objects with a type that corresponds to the object that has the duplicate rules you want to use.
2. In each sObject, specify record IDs or field maps (or both) to compare to records in the object.
3. Set DuplicateRuleHeader to control the output you want.

Sample

The following Java sample demonstrates how to search for duplicates of a Lead, using the standard Leads duplicate rule.

package wsc;

import com.sforce.soap.partner.*;
import com.sforce.soap.partner.Error;
import com.sforce.soap.partner.sobject.SObject;
import com.sforce.ws.ConnectionException;
import com.sforce.ws.ConnectorConfig;

public class Main {

  private static final String USERNAME = "YOUR-USERNAME";
  private static final String PASSWORD = "YOUR-PASSWORD&SECURITY-TOKEN";
  private static PartnerConnection connection = null;

  public static void main(String[] args) throws ConnectionException {

    // Create the configuration for the partner connection
    ConnectorConfig config = new ConnectorConfig();
    config.setUsername(USERNAME);
    config.setPassword(PASSWORD);

    // Initialize the connection
    connection = new PartnerConnection(config);

    SObject[] inputSObjectArray = new SObject[1];
    // Instantiate an empty Java SObject
    SObject searchCriteria = new SObject();
    // Set its type to Lead. This tells findDuplicates() to use the duplicate rules
    // for Lead
    searchCriteria.setType("Lead");
    /*
     * Set the necessary fields for matching, based on the standard matching rules for Lead (Search
     * help.salesforce.com for "Standard Contact and Lead Matching Rule" to see the rules).
     */
    searchCriteria.setField("FirstName", "Marc");
    searchCriteria.setField("LastName", "Benioff");
    searchCriteria.setField("Company", "Salesforce.com Inc");
    searchCriteria.setField("Title", "CEO");
    searchCriteria.setField("Email", "ceo@salesforce.com");
    // Add the sObject to the input array
    inputSObjectArray[0] = searchCriteria;
    /*
     * By default, findDuplicates() returns only record IDs. To return additional values, set the second parameter
     * to true.
     */
    connection.setDuplicateRuleHeader(
        /*
         * @param allowSave - Not Applicable for this API call
         */
        false,
        /* @param includeRecordDetails */
        false,
        /*
         * @param runAsCurrentUser - Not Applicable for this API call
         */
        false);

    // Invoke findDuplicates() to find duplicates based on the information in the
    // SObject array
    FindDuplicatesResult[] callResults = connection.findDuplicates(inputSObjectArray);

    // Iterate through the results
    // For each SObject in the input array, get the duplicate results
    for (FindDuplicatesResult findDupeResult : callResults) {
      // If errors were found for this SObject, print them out
      if (!findDupeResult.isSuccess()) {
        for (Error findDupError : findDupeResult.getErrors()) {
          System.out.println("FindDuplicatesRule errors detected: " + findDupError.getMessage());
        }
      } else {
        /*
         * Get the DuplicateResult object array for the result. Each element in the array represents the result
         * of testing one duplicate rule for the SObject. Process each DuplicateResult.
         */
        for (DuplicateResult dupeResult : findDupeResult.getDuplicateResults()) {
          System.out.println("Duplicate rule: " + dupeResult.getDuplicateRule());
          // Print out the name of the object associated with the duplicate
          // rule
          System.out.println("Source of this duplicate rule is: " + dupeResult.getDuplicateRuleEntityType());
          for (MatchResult matchResult : dupeResult.getMatchResults()) {
            if (!matchResult.isSuccess()) {
              for (Error e : matchResult.getErrors()) {
                System.out.println("Errors detected: " + e.getMessage());
              }
            } else {
              System.out.println("Matching rule is: " + matchResult.getRule());
              System.out.println("Object type for this matching rule is: " + matchResult.getEntityType());
              for (MatchRecord matchRecord : matchResult.getMatchRecords()) {
                System.out.println("Duplicate record ID: " + matchRecord.getRecord().getId());
              }
            }
          }
        }
      }
    }
  }
}

Arguments

Response

An array of FindDuplicatesResult objects.

FindDuplicatesResult

Represents the result of a duplicate search for a single sObject in the input array. Because the object associated with the sObject can have more than one duplicate rule, FindDuplicatesResult contains an array of DuplicateResult objects.

Fields

Faults

InvalidFieldFault

InvalidSObjectFault

UnexpectedErrorFault