Using the Qualify Lead Action in Dynamics 365

Isaac Stephens, 22 July 2019

Dynamics 365 lets you convert a Lead into an Account, Contact and Opportunity at a click of a button. But you may not need to have an opportunity created, which means you will either need to delete these unwanted records, or just let them sit there wasting your precious space.

Well luckily enough, for these situations Dynamics 365 allows you to make a Custom ‘Qualify Lead’ using an Out-of-the-Box action called ‘Qualify Lead’. This action allows you to choose what it does while qualifying the lead. These options are shown below:

The No Code Way:

For a basic and quick no code solution you can create a real time on-demand workflow for a Lead. This will then call the action and process it with the options selected. In this example we don’t need an Opportunity so that option was set to false.

Once activated this will then show in the Ribbon on the Lead record under the Flow dropdown.

The one negative of this is that the Out-of-the-Box ribbon button for Qualifying Leads then opens up the created Opportunity. However, when using the action to throw a workflow, we cannot open up the created record. This may or may not be an issue but there is another way to qualify leads that means you can do this.

The Code Way:

The JavaScript way allows us a bit more control and in conjunction with the Ribbon Workbench, allows us to reuse the existing ‘Qualify Lead’ button. The Code used to call the action is shown below in two parts. The first part handles executing the request and the response and the second part handles the creation of the request.

This function calls WebApi.online.execute() and passes in the generated actionRequest. It then checks the response and on success it checks that an account was created and opens that account. So the user knows something is happening we also show a loading screen while the request is taking place using Xrm.Utility.showProgressIndicator().

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

BLOG.qualifyLead = function (executionContext) {
    Xrm.Utility.showProgressIndicator();
    var leadRef = executionContext.data.entity.getEntityReference();
 
    var actionRequest = new BLOG.qualifyLeadRequest(leadRef);
    Xrm.WebApi.online.execute(actionRequest).then(
        function (result) {
            if (result.ok) {
                result.json().then(function (response) {
                    var accountId = "";
 
                    response.value.forEach(function (record) {
                        if ("accountid" in record) {
                            accountId = record.accountid;
                        }
                    }
                    );
                    if (accountId != "") {
                        Xrm.Navigation.openForm({ entityName: "account", entityId: accountId });
                    }
                });
            }
        },
        function (error) {
            alert(error.message);
	   Xrm.Utility.closeProgressIndicator();
        }
    );
}

This JavaScript function creates action request to be handed into the WebApi.online.execute function. Here you will set parameters for the Qualify Lead action, in this example an Account and Contact will be created but no Opportunity.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

BLOG.qualifyLeadRequest = function (leadRef) {

    this.entity = leadRef;
    this.CreateAccount = true;
    this.CreateContact = true;
    this.CreateOpportunity = false;
    this.OpportunityCurrencyId = null;
    this.OpportunityCustomerId = null;
    this.SourceCampaignId = null;
    this.Status = 3;
    this.ProcessInstanceId = null; 
    this.getMetadata = function () {
        return {
            boundParameter: "entity",
            parameterTypes: {
                "entity": {
                    "typeName": "mscrm.lead”, "structuralProperty": 5
                },
                "CreateAccount": {
                    "typeName": "Edm.Boolean", "structuralProperty": 1
                },
                "CreateContact": {
                    "typeName": "Edm.Boolean", "structuralProperty": 1
                },
                "CreateOpportunity": {
                    "typeName": "Edm.Boolean", "structuralProperty": 1
                },
                "OpportunityCurrencyId": {
                    "typeName": "mscrm.transactioncurrency", structuralProperty": 5
                },
                "OpportunityCustomerId": {
                    "typeName": "mscrm.crmbaseentity", "structuralProperty": 5
                },
                "SourceCampaignId": {
                    "typeName": "mscrm.campaign", "structuralProperty": 5
                },
                "Status": {
                    "typeName": "Edm.Int32", "structuralProperty": 1
                },
                "ProcessInstanceId": {
                    "typeName": "mscrm.crmbaseentity", "structuralProperty": 5
                }
            },
            operationType: 0,
            operationName: "QualifyLead"
        };
    };
}

Another useful feature of the Qualify Lead action is the SuppressDuplicationDetection parameter. This parameter can be set to ensure that no duplicate detection rules will be applied during execution. It’s important to note that all plugins that run off create/update of a record created/updated during the execution request will, by default, have duplication detection rules applied to them. So, to ensure that no rules are applied you must set this parameter to ‘true’. If you still want these rules to apply then, either, set it to false or don’t set it at all. Just add the first line with the other object parameters and the second part the end of the getMetadata function.

1
2
3
4
5
6

1)    this.SuppressDuplicateDetection = true  // or false
                

2)   "SuppressDuplicateDetection": {
         "typeName": "Edm.Boolean", "structuralProperty": 1
     }

If a duplicate detection rule is triggered it will trigger the on-Error call-back function, in this case displaying the alert below.

This example was just a basic implementation of a custom Lead Qualification. You can add more custom code to tailor what happens with the response to best suit your company’s needs. You can even add extra code to bring over more fields, such as custom fields on the lead, that you want applied to the newly created Account, Contact, or Opportunity.