Oracle Web Services On Demand Guide > Web Services On Demand API Calls > Service API Calls >

MergeRecords

Merges records for certain record types.

Objects Supported

MergeRecords is only supported for the Account, Contact, Division, Household, Lead, and Portfolio record types. If an invalid record type is provided, an error message is displayed.

Usage

You use the MergeRecords method to merge records. When you merge two records, you specify the record that you want to keep, which is called the primary record, and the record that is to be deleted, which is called the duplicate record.

You must identify a reference to a primary record and a reference to a duplicate record in the request. To identify the primary record, you must specify either a PrimaryId or a PrimaryExternalSystemId argument. To identify the duplicate record, you must specify either a DuplicateId or a DuplicateExternalSystemId argument.

The following rules apply to merging records:

• Fields in the primary parent record that contain data are retained.
• Fields in the primary record that are blank get the value from the duplicate record, if it has a value and if the MergeWhenPrimaryBlank argument is set to true.
• Fields in the primary parent record that are blank remain blank, if the MergeWhenPrimaryBlank argument is not set, or is set to a value other than true.

The MergeDuplicateBooks argument together with the Enable Merge of Duplicate Record's Books setting in the company profile determine whether the books of duplicate records are added to the primary record:

• If the company profile setting is not selected, OR if the company profile setting is selected AND the MergeDuplicateBooks argument is not set to true, then the duplicate record's books are not added to the primary record.
• If the company profile setting is selected AND the MergeDuplicateBooks argument is set to true, then the duplicate record's books are added to the primary record.

The Merge Web service has the same security restrictions as in the Oracle CRM On Demand UI regarding privilege and record permissions.

Table 56 describes the arguments taken by MergeRecords.

Possible Reasons for Failure of the Merge Operation

If there are more than 9999 records of any one record type linked to either of the records that you want to merge, then the merge operation will not complete successfully. Also, if there are large numbers of records of any type linked to either of the records that you want to merge, then the merge operation might time out, even if the number of linked records of any one record type does not exceed 9999. Other factors can also cause a merge operation to time out, such as the types of records that are involved in the merge operation, the speed of your network, and the load on the Oracle CRM On Demand database and server. You can work around these issues by doing the following:

• Unlink some of the linked records from the parent record as necessary before you merge the parent records.
• Perform merge operations during off-peak hours.

Return Value of the Call

The following four values are returned:

• MergedRecordId. The ID of the merged record, that is, the primary record.
• MergedRecordExternalId. The externalsystemID of the merged record.
• DeletedRecordId. The ID of the deleted record, that is, the duplicate record.
• DeletedRecordExternalId. The externalsystemID of the merged record.

Sample SOAP Request - MergeRecords

The following SOAP request merges a contact record with DuplicateExternalSystemId = abc223 into a contact record with Id = ADSA-93DZIC.

NOTE:  To identify the primary record, you can specify either the <PrimaryId> or <PrimaryExternalSystemId> argument, and to specify the duplicate record you can use either the <DuplicateId> or <DuplicateExternalSystemId> argument.

The sample also demonstrates passing in the optional <MergeWhenPrimaryBlank> argument to copy the value for a field in the duplicate record to the primary record when the field in the primary record is blank.

<?xml version="1.0" encoding="utf-8" standalone="no"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

   <soap:Header>

      <wsse:Security>

         <wsse:UsernameToken>

            <wsse:Username>%%%USERNAME%%%</wsse:Username>

            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">%%%PASSWORD%%%</wsse:Password>

         </wsse:UsernameToken>

      </wsse:Security>

   </soap:Header>

   <soap:Body>

      <MergeRecordsWS_MergeRecords_Input xmlns="urn:crmondemand/ws/mergerecords/">

         <PrimaryId>ADSA-93DZIC</PrimaryId>

         <DuplicateExternalSystemId>abc223</DuplicateExternalSystemId>

         <MergeWhenPrimaryBlank>Y</MergeWhenPrimaryBlank>

         <RecordType>Contact</RecordType>

      </MergeRecordsWS_MergeRecords_Input>

   </soap:Body>

</soap:Envelope>

Sample SOAP Response

The following response contains the IDs of the merged and deleted records:

<?xml version="1.0" encoding="utf-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

   <SOAP-ENV:Body>

      <ns:MergeRecordsWS_MergeRecords_Output xmlns:ns="urn:crmondemand/ws/mergerecords/">

         <ns:DeletedRecordExternalSystemId>abc223</ns:DeletedRecordExternalSystemId>

         <ns:DeletedRecordId>ADSA-93ET5I</ns:DeletedRecordId>

         <ns:MergedRecordExternalSystemId>ABC123</ns:MergedRecordExternalSystemId>

         <ns:MergedRecordId>ADSA-93DZIC</ns:MergedRecordId>

      </ns:MergeRecordsWS_MergeRecords_Output>

   </SOAP-ENV:Body>

</SOAP-ENV:Envelope>