Once our Microsoft Dynamics CRM system has been configured with the required duplicate detection settings and the duplicate detection rules, we can start detecting duplicates. Let us go through a sequence of steps to see how run-time duplicate detection can be made to work.
1. Using run-time duplicate detection.
So, we are all set for our run-time duplicate detection. Now, we need to detect duplicates during create/update of records in Microsoft Dynamics CRM.
Titan introduces a notion of Optional Parameters that can be used to pass optional information to each of the SDK Methods. The run-time duplicate detection feature also makes use of an optional parameter. Let us see how.
// Run-time duplicate detection
_myAccount = new account();
…
TargetCreateAccount target = new TargetCreateAccount();
target.Account = _myAccount;
// Optional parameter: Do not create duplicates
OptionalParameter optionalParameter_1 = new CreateDuplicatesOptionalParameter(false);
// Optional parameter: Generate matchcodes synchronously
OptionalParameter optionalParameter_2 = new PersistInSyncOptionalParameter(true);
CreateRequest request = new CreateRequest();
request.Target = target;
request.OptionalParameters = new OptionalParameter[] { optionalParameter_1, optionalParameter_2 };
try
{
CreateResponse response = (CreateResponse) _crmService.Execute(request);
}
catch (SoapException e)
{
…
if (GetErrorCode(e) == ErrorCodes.DuplicateRecordsFound)
{
// Duplicate Found
…
}
…
}
Notes:
1. Duplicate detection will not work with the Create or Update methods of CrmService object. It will work with Execute method only.
2. Optional parameter PersistInSync is used to keep generating match-codes synchronously with the record creation. This makes duplicate detection real-time and is useful when pumping-in records in bulk. However, persisting match-codes synchronously may cause the throughput of Create/Update calls to go down.
The default value for CreateDuplicates optional parameter is true in order to keep parity with V3 behavior. If the parameter is not specified or set as true, then the record gets created without a duplicate check.
The default value for PersistInSync optional parameter is false as it gives a better throughput for the create/update SDK call. The flip side, however, is that the duplicate detection is not real-time and duplicates of newly created/updated records may not get reported unless their match-codes have been updated by the periodic asynchronous job responsible for updating match-codes.
2. Retrieving duplicate records.
Okay, so far so good. I have got an exception saying that the record I am trying to create/update is a duplicate. But now, how do I fetch the record(s) of which my record is a potential duplicate? Don’t worry; we have one more SDK method to help solve your problem!
Once you know that the record you are trying to create is a duplicate, you can fetch the duplicates of that record using RetrieveDuplicates SDK message.
// Retrieve duplicates of an entity instance
PagingInfo pageInfo = new PagingInfo();
pageInfo.Count = 50;
pageInfo.PageNumber = 1;
RetrieveDuplicatesRequest request = new RetrieveDuplicatesRequest();
request.BusinessEntity = _myAccount;
request.MatchingEntityName = EntityName.account.ToString();
request.PagingInfo = pageInfo;
RetrieveDuplicatesResponse response = null;
try
{
response = (RetrieveDuplicatesResponse)_crmService.Execute(request);
// Duplicate records collection
BusinessEntityCollection duplicates = response.DuplicateCollection;
}
catch (SoapException e)
{
…
}
The matching entity name can be specified based on the published rules for a base entity. E.g. in our case we have a published duplicate detection rule for account entity where matching entity is also account. So, we fetched all the accounts in the system of which our record is a duplicate. Please refer to the appendix for more details.
Note: The run-time duplicate detection and the records returned by RetrieveDuplicates method are privilege driven. So the run-time duplicate detection may not report a duplicate if the user does not have read privilege on the duplicate record even though it is there in the system.
For the custom tool the company wants to build, as soon as a duplicate record found exception is caught, the RetrieveDuplicates SDK message can be used to find the duplicate records already in system. Then, these records can be handled as per the requirement like updating the existing record with any new information that the incoming record may have. Alternatively, other rules/schemes could be used to merge the set of duplicate records.
This is how simple it is for you to use the duplicate detection SDK and build custom applications on top of it! It is extremely powerful and at the same time ever so naïve and flexible to use!
Next I will cover Bulk Duplicate Detection.