The Intro is here in case you missed it.
The first step required for detecting duplicates is to configure the system by enabling the duplicate detection settings and setting up duplicate detection rules. Since the CRM Titan comes pre-configured for some basic duplicate detection scenarios, including the one we are going to discuss in this section, readers interested specifically in run-time duplicate detection may choose to skip this section.
Let us now see what steps are needed for configuring the Microsoft Dynamics CRM to detect duplicates:
1. Enable duplicate detection for the organization.
There is a global, organization level setting for duplicate detection which controls whether duplicate detection is enabled for the organization. We need to enable the setting using the Update SDK Message.
// Enable duplicate detection for organization
organization myOrg = new organization();
myOrg.organizationid = new Key(_organizationId);
…
myOrg.isduplicatedetectionenabled = new CrmBoolean(true);
TargetUpdateOrganization target = new TargetUpdateOrganization();
target.Organization = myOrg;
UpdateRequest request = new UpdateRequest();
request.Target = target;
try
{
UpdateResponse response = (UpdateResponse) _crmService.Execute(request);
}
catch (SoapException e)
{
…
}
Note: Duplicate Detection is enabled for an organization OOB.
2. Enable duplicate detection for the entity.
Every entity in CRM has a metadata property that says whether the entity supports duplicate detection. Alternatively put, whether the entity can participate in duplicate detection rules. We can update this metadata attribute by using the metadata service Update SDK Message.
// Enable duplicate detection for account entity
EntityMetadata entityMetadata = new EntityMetadata();
entityMetadata.LogicalName = EntityName.account.ToString();
…
entityMetadata.DuplicateDetection = new CrmBoolean(true);
UpdateEntityRequest request = new UpdateEntityRequest();
request.Entity = entityMetadata;
try
{
UpdateEntityResponse response = (UpdateEntityResponse) _metadataService.Execute(request);
}
catch (SoapException e)
{
…
}
Note: Duplicate Detection is enabled for account entity OOB.
3. Create duplicate detection rule.
Now we are ready to create our own duplicate detection rule for detecting duplicates. A duplicate rule consists of a number of duplicate rule conditions.
We need to create a duplicate rule with one duplicate rule condition. Lets see how we can create a rule that says an Account is a duplicate of itself it they have the same email address.
// Create duplicate rule object
duplicaterule rule = new duplicaterule();
rule.name = “Accounts with the same e-mail address”;
rule.baseentityname = EntityName.account.ToString();
rule.matchingentityname = EntityName.account.ToString();
rule.iscasesensitive = new CrmBoolean(false);
// Create duplicate rule condition objects
duplicaterulecondition ruleCondition = new duplicaterulecondition();
ruleCondition.operatorcode = new CrmBoolean((int)DuplicateRuleOperator.Equals);
ruleCondition.operatorparam = null;
ruleCondition.baseattributename = “emailaddress1”;
ruleCondition.matchingattributename = “emailaddress1”;
duplicaterulecondition[] ruleConditions = new duplicaterulecondition[] { ruleCondition };
// Create duplicate rule with duplicate rule conditions in one go
TargetCompoundDuplicateRule target = new TargetCompoundDuplicateRule();
target.DuplicateRule = rule;
target.DuplicateRuleConditions = ruleConditions;
CompoundCreateRequest request = new CompoundCreateRequest();
request.Target = target;
try
{
CompoundCreateResponse response = (CompoundCreateResponse) _crmService.Execute(request);
_ruleId = response.Id;
}
catch (SoapException e)
{
…
}
// Alternatively, we can create duplicate rule and duplicate rule
// conditions separately using Create SDK Message
Note: “Accounts with the same e-mail address” duplicate detection rule is available OOB.
One can also create cross entity duplicate detection rules with the same ease. For instance, if I want to setup a rule saying that an Account is a duplicate of Contact if they both have the same email address, then I would just need to set the matching entity name to contact and the matching attribute name to contact’s email address attribute:
rule.matchingentityname = EntityName.contact.ToString();
ruleCondition.matchingattributename = “emailaddress1”;
4. Publish duplicate detection rule.
After we have created the duplicate detection rule, we need to publish the rule for it to participate in duplicate detection. Publishing a rule generates match-codes for all the records in the system of the participating entity types and makes them available for duplicate detection. Since, duplicate rule publish is a bulk job, it is processed in the background by the CRM Asynchronous Service.
Let us now see how we can publish the rule we created above.
// Publish duplicate detection rule
PublishDuplicateRuleRequest request = new PublishDuplicateRuleRequest();
request.DuplicateRuleId = _ruleId;
try
{
PublishDuplicateRuleResponse response = (PublishDuplicateRuleResponse)_crmService.Execute(request);
_jobId = response.JobId;
}
catch (SoapException e)
{
…
}
// Poll the status of the asynchronous job
TargetRetrieveAsyncOperation target = new TargetRetrieveAsyncOperation();
target.EntityId = _jobId;
ColumnSet columns = new ColumnSet();
columns.Attributes = new String[] { “statecode”, “statuscode” };
RetrieveRequest retrieve = new RetrieveRequest();
retrieve.Target = target;
retrieve.ColumnSet = columns;
while (_stateCode != AsyncOperationState.Completed)
{
try
{
RetrieveResponse response = (RetrieveResponse)_crmService.Execute(retrieve);
asyncoperation operation = response.BusinessEntity;
_stateCode = operation.statecode.Value;
}
catch (SoapException e)
{
…
}
}
Note: Once the rule gets published, the system automatically keeps the match-codes up-to-date by running periodic asynchronous jobs in the background.
In the next post I’ll talk about Run-time Duplicate Detection.