Newer Version Available
merge()
Merge up to three records into one.
Syntax
1MergeResult[]= connection.merge(MergeRequest[] mergeRequests);Usage
Use this call to merge records of the same object type into one of the records, deleting the others, and re-parenting any related records. Each merge operation is within one transaction. A batch merge has multiple transactions, one for each element in the batch.
The only supported object types are Lead, Contact and Account.
The masterRecord field indicates which of the records is the master record that the others are merged into. You can use queryAll() to view records that have been deleted during a merge.
This call requires that you decide prior to the merge call if there are any field values from the non-master record(s) that should supersede the values in the master record. If so, the field names and their new values should be set in the masterRecord of the MergeRequest, similar to a call to update.
- Up to 200 merge requests can be made in a single SOAP call.
- Up to three records can be merged in a single request, including the master record. This is the same limit as the Salesforce user interface. If you have more than three records to merge, use the same master record in each request to avoid errors.
- External ID fields cannot be used with merge().
To find all records that have been merged since a given point in time, you can use queryAll() with a SELECT statement similar to the following:
1SELECT Id FROM Contact WHERE isDeleted=true and masterRecordId != null
2 AND SystemModstamp > 2006-01-01T23:01:01+01:00It is a recommended best practice to narrow your result set to the most relevant records by filtering on SystemModstamp.
Sample Code—Java
This sample merges one account with a master account. It creates two accounts and attaches a note to the account to merge with the master. After the merge, it writes the ID of the account that was merged and the number of child records updated, which in this case is one because the note of the merged account is moved to the master account.
1swfobject.registerObject("clippy.codeblock-2", "9");
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17public Boolean mergeRecords() {
18 Boolean success = false;
19 // Array to hold the results
20 String[] accountIds = new String[2];
21 try {
22 // Create two accounts to merge
23 Account[] accounts = new Account[2];
24 Account masterAccount = new Account();
25 masterAccount.setName("MasterAccount");
26 masterAccount.setDescription("The Account record to merge with.");
27 accounts[0] = masterAccount;
28 Account accountToMerge = new Account();
29 accountToMerge.setName("AccountToMerge");
30 accountToMerge
31 .setDescription("The Account record that will be merged.");
32 accounts[1] = accountToMerge;
33 SaveResult[] saveResults = connection.create(accounts);
34
35 if (saveResults.length > 0) {
36 for (int i = 0; i < saveResults.length; i++) {
37 if (saveResults[i].isSuccess()) {
38 accountIds[i] = saveResults[i].getId();
39 System.out.println("Created Account ID: "
40 + accountIds[i]);
41 } else {
42 // If any account is not created,
43 // print the error returned and exit
44 System.out
45 .println("An error occurred while creating account."
46 + " Error message: "
47 + saveResults[i].getErrors()[0].getMessage());
48 return success;
49 }
50 }
51 }
52
53 // Set the Ids of the accounts
54 masterAccount.setId(accountIds[0]);
55 accountToMerge.setId(accountIds[1]);
56
57 // Attach a note to the account to be merged with the master,
58 // which will get re-parented after the merge
59 Note note = new Note();
60 System.out.println("Attaching note to record " +
61 accountIds[1]);
62 note.setParentId(accountIds[1]);
63 note.setTitle("Merged Notes");
64 note.setBody("This note will be moved to the "
65 + "MasterAccount during merge");
66 SaveResult[] sRes = connection.create(new SObject[] { note });
67 if (sRes[0].isSuccess()) {
68 System.out.println("Created Note record.");
69 } else {
70 Error[] errors = sRes[0].getErrors();
71 System.out.println("Could not create Note record: "
72 + errors[0].getMessage());
73 }
74
75 // Perform the merge
76 MergeRequest mReq = new MergeRequest();
77 masterAccount.setDescription("Was merged");
78 mReq.setMasterRecord(masterAccount);
79 mReq.setRecordToMergeIds(new String[] { saveResults[1].getId() });
80 MergeResult mRes = connection.merge(new MergeRequest[] { mReq })[0];
81
82 if (mRes.isSuccess())
83 {
84 System.out.println("Merge successful.");
85 // Write the IDs of merged records
86 for(String mergedId : mRes.getMergedRecordIds()) {
87 System.out.println("Merged Record ID: " + mergedId);
88 }
89 // Write the updated child records. (In this case the note.)
90 System.out.println(
91 "Child records updated: " + mRes.getUpdatedRelatedIds().length);
92 success = true;
93 } else {
94 System.out.println("Failed to merge records. Error message: " +
95 mRes.getErrors()[0].getMessage());
96 }
97 } catch (ConnectionException ce) {
98 ce.printStackTrace();
99 }
100 return success;
101}Sample Code—C#
This sample merges one account with a master account. It creates two accounts and attaches a note to the account to merge with the master. After the merge, it writes the ID of the account that was merged and the number of child records updated, which in this case is one because the note of the merged account is moved to the master account.
1swfobject.registerObject("clippy.codeblock-3", "9");
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17public Boolean mergeRecords()
18{
19 Boolean success = false;
20 // Array to hold the results
21 String[] accountIds = new String[2];
22 try
23 {
24 // Create two accounts to merge
25 Account[] accounts = new Account[2];
26 Account masterAccount = new Account();
27 masterAccount.Name = "MasterAccount";
28 masterAccount.Description = "The Account record to merge with.";
29 accounts[0] = masterAccount;
30 Account accountToMerge = new Account();
31 accountToMerge.Name = "AccountToMerge";
32 accountToMerge
33 .Description = "The Account record that will be merged.";
34 accounts[1] = accountToMerge;
35 SaveResult[] saveResults = binding.create(accounts);
36
37 if (saveResults.Length > 0)
38 {
39 for (int i = 0; i < saveResults.Length; i++)
40 {
41 if (saveResults[i].success)
42 {
43 accountIds[i] = saveResults[i].id;
44 Console.WriteLine("Created Account ID: "
45 + accountIds[i]);
46 }
47 else
48 {
49 // If any account is not created,
50 // print the error returned and exit
51 Console.WriteLine("An error occurred while creating account."
52 + " Error message: "
53 + saveResults[i].errors[0].message);
54 return success;
55 }
56 }
57 }
58
59 // Set the Ids of the accounts
60 masterAccount.Id = accountIds[0];
61 accountToMerge.Id = accountIds[1];
62
63 // Attach a note to the account to be merged with the master,
64 // which will get re-parented after the merge
65 Note note = new Note();
66 Console.WriteLine("Attaching note to record " +
67 accountIds[1]);
68 note.ParentId = accountIds[1];
69 note.Title = "Merged Notes";
70 note.Body = "This note will be moved to the "
71 + "MasterAccount during merge";
72 SaveResult[] sRes = binding.create(new sObject[] { note });
73 if (sRes[0].success)
74 {
75 Console.WriteLine("Created Note record.");
76 }
77 else
78 {
79 Error[] errors = sRes[0].errors;
80 Console.WriteLine("Could not create Note record: "
81 + errors[0].message);
82 }
83
84 // Perform the merge
85 MergeRequest mReq = new MergeRequest();
86 masterAccount.Description = "Was merged";
87 mReq.masterRecord = masterAccount;
88 mReq.recordToMergeIds = new String[] { saveResults[1].id };
89 MergeResult mRes = binding.merge(new MergeRequest[] { mReq })[0];
90
91 if (mRes.success)
92 {
93 Console.WriteLine("Merge successful.");
94 // Write the IDs of merged records
95 foreach (String mergedId in mRes.mergedRecordIds)
96 {
97 Console.WriteLine("Merged Record ID: " + mergedId);
98 }
99 // Write the updated child records. (In this case the note.)
100 Console.WriteLine(
101 "Child records updated: " + mRes.updatedRelatedIds.Length);
102 success = true;
103 }
104 else
105 {
106 Console.WriteLine("Failed to merge records. Error message: " +
107 mRes.errors[0].message);
108 }
109 }
110 catch (SoapException e)
111 {
112 Console.WriteLine("An unexpected error has occurred: " +
113 e.Message + "\n" + e.StackTrace);
114 }
115 return success;
116}Arguments
This call accepts an array of MergeRequest objects. A MergeRequest object contains the following properties.
| Name | Type | Description |
|---|---|---|
| masterRecord | sObject | Required. Must provide the ID of the object that other records will be merged into. Optionally, provide the fields to be updated and their values. |
| recordToMergeIds | ID[] | Required. Minimum of one, maximum of two. The other record or records to be merged into the master record. |