Salesforce Custom Convert Lead Page and Lead Conversion Process Using Visualforce and Apex

There are a number of “Black Box” processes in Salesforce that are essentially hardcoded functions that you have little or no control over. The out-of-the-box Lead Conversion process is one of these Black Box processes – when you click the standard ‘Convert’ button from a Lead record, you get redirected to a page called leadconvert.jsp.

While the standard page used for lead conversion is good enough most of the time for most customers, you may eventually find yourself asking, “How do I customize the Convert Lead screen?

We figured the Salesforce community would get value from a customizable lead conversion page and process, so we built one by recreating the Convert Lead page using Visualforce, Javascript, and Apex and published it as an unmanaged package on the AppExchange. By publishing as an unmanaged package, you get full access to the Apex classes, Visualforce pages, and Visualforce components and can customize them to create your own lead conversion process for your Salesforce org.

What are the use cases for a custom Convert Lead page for converting Salesforce leads?

  • Include additional Opportunity, Account or Contact fields when converting a Lead
  • Hide fields on the Convert Lead page
  • Prevent users from creating new Opportunities when converting a Lead
  • Remove the Task fields from the Convert Lead page
  • Include additional custom buttons on the Convert Lead page
  • Add or remove sections and manage the style and formatting of the Convert Lead page
  • Implement custom or complex field mapping logic
  • Map Lead fields to multiple fields on the converted Opportunity, Account or Contact
  • Select an Account or Opportunity Record Type when converting a Lead
  • Redirect to a different object or screen after converting a Lead
  • Include a custom update on the Chatter feeds for converted records
  • Add Products to Opportunities at the time of lead conversion
  • Include logic to set default options and values when converting Leads
  • Copy Lead field values to custom objects upon conversion

How does the custom Convert Lead page work?

We studied how the standard Salesforce Lead conversion process worked from end-to-end, and built an exact replica of the Convert Lead page using Visualforce and Apex. The result is an unmanaged package of Apex classes, custom Visualforce components, and a Visualforce page that you can use as a starting point for customizing the lead conversion process to the exact requirements of your business users.

The Convert Lead unmanaged package contains the following components:

Visualforce Page
  • leadConvertPage – The Visualforce page that replicates the standard Convert Lead page and uses the Standard Controller for the Lead sObject
Visualforce Components
  • leadConvertCoreComponent – Visualforce component containing the core UI elements for the Visualforce page
  • leadConvertTaskDescriptionComponent – Visualforce component containing UI elements related to the Task Description
  • leadConvertTaskInfoComponent – Visualforce component containing UI elements related to the common Task fields
  • leadConvertPageHeaderTextComponent – Visualforce component containing text that appears at the top of the Visualforce page
Apex Classes
  • ComponentControllerBase – Core Visualforce component controller
  • DateTimeUtility – Utility class containing Date / Time functions
  • leadConvertController – Visualforce controller extension
  • leadConvertCoreComponentController – Controller for the leadConvertCoreComponent Visualforce component
  • leadConvertTaskDescComponentController – Controller for the leadConvertTaskDescriptionComponent Visualforce component
  • leadConvertTaskInfoComponentController – Controller for the leadConvertTaskInfoComponent Visualforce component
  • PageControllerBase – Helper class to manage communications between the Visualforce page and components
  • TestLeadConvertPage – Unit tests for all Apex classes in the Convert Lead package

How do I use the custom Convert Lead page?

Implementing the custom Visualforce page is straightforward. You can choose to use either a standalone Custom Button (an example is included in the package) or overwrite the standard Convert button on the Lead object.

To use the Custom Button, simply drag it onto the desired Page Layouts from the Page Layout editor and optionally remove the standard Convert button from the page.

To override the standard Convert button, navigate to ‘Buttons, Links, and Actions’ in the Customize options for the Lead object. Click the ‘Edit’ link next to the Convert button, set the ‘Override With’ option to ‘Visualforce Page,’ and select the ‘leadConvertPage’ Visualforce page from the dropdown menu.

Where can I find the Convert Lead unmanaged package?

You can use the following link to the private AppExchange listing to download the app into your Unlimited Edition, Enterprise Edition, or Developer Edition org:

Custom Salesforce Lead Convert on AppExchange

Something to keep in mind – because this is an unmanaged package, updates to the package will not be applied to any Salesforce orgs in which the package is installed. We will be updating the package regularly based on feedback from the community, so when you see an update available you can download it, but you will need to manually apply any changes to your customized version of the application.

Mike Topalovich Salesforce Technical Architect in Chicago
Mike Topalovich - Salesforce Certified Force.com Platform Developer I Mike Topalovich - Salesforce Certified Force.com Platform Developer II Mike Topalovich - Salesforce Certified Force.com Developer Mike Topalovich - Salesforce Certified Force.com Advanced Developer
Mike Topalovich - Salesforce Certified Mobile Solutions Architecture Designer Mike Topalovich - Salesforce Certified Force.com Platform App Builder Mike Topalovich - Salesforce Certified Administrator Mike Topalovich - Salesforce Certified Advanced Administrator
Mike Topalovich

Hi, I’m Mike. I help companies like yours do business in new ways with Salesforce.


I am a freelance Salesforce Developer, Architect, and CTO as well as a part time instructor for Salesforce University.


Connect with me today to discuss how I can become a part of your team on an ongoing retainer basis.


Mike Topalovich on EmailMike Topalovich on FlickrMike Topalovich on LinkedinMike Topalovich on RssMike Topalovich on Twitter

46 Comments

  1. Sarah Stiffler

    I have installed this and configured the basics and it seems to be working. I would like to put logic around the account lookup in the future but for now this is awesome!

    Reply

  2. Ashley Terry

    I uncommented the code and I am getting errors I want to remove the opportunity from the lead conversion page.

    Reply

    • John Brotherton

      I would love this as well. I am so close to deploying this, but the Opportunity piece has got to go! That’s the final bit for me.

      Reply

  3. rhooseboy

    HI – this is a neat package – I’ve installed it and got a custom VF convert page now without the Required markings on the non-required fields. I am having issues with data.com duplicate management. Have yo come across any solutions to replicate the duplicate detection page during conversion that offers any duplicate records and shows the Save as New and Save as Existing buttons?

    Reply

    • Mike Topalovich

      Unfortunately that’s above my pay grade…I’m not familiar with data.com at all and not sure how it works with regard to the Salesforce API.

      Reply

  4. Karl Laird

    This looks fantastic – at least for customizing Classic; however I’m not having much joy in Lightning
    Any plans to make a Lightning compatible version?

    Reply

    • Mike Topalovich

      I’m working on rewriting this as a Lightning Component for an upcoming book for Packt Publishing. I will see about pre-releasing this on the blog.

      Reply

      • Megan Hooser

        Is there any update on this? Just found this and thought it was our answer, except we are running in Lightning.

        Reply

        • Mike Topalovich

          The new lead convert process in Winter 18 is pretty robust…what are you trying to do that you can’t do out of the box?

          Reply

  5. Oded

    I am facing one issue preventing me from completing this – regardless of what I select in Account I keep getting “Please select an Account.” error. Any idea why?

    Reply

  6. Ralf

    Very nice and works great.
    Unless I’m doing something wrong, the standard process to attach new contact to existing one seems to be missing. Are there any plans to add that?

    Reply

  7. Dnyaneshwar Kendre

    Hi,

    I have visual force page embedded in Lead page layout. Upon Lead conversion its showing :Record type unavailable error.

    I have default record types in place for all objects and also person account is enabled. So i am thinking the error is due to VF page in lead layout, I am correct? Do you know any workaround for the error.

    Thanks a ton!

    Reply

    • Mike Topalovich

      I don’t believe the embedding would have anything to do with the error. It sounds like a record type ID is being applied to the newly created Account or Contact incorrectly…if Person Accounts are enabled, you may have to explicitly provide the ID of the record type corresponding to the company (non-person) account type.

      Reply

  8. Tonya

    How do I default check “send email to the owner” and Do not create a new opportunity upon conversion” check boxes?

    Reply

    • Mike Topalovich

      It’s been a while since I’ve looked at the code in the package, but I believe if you just set the corresponding Boolean property values to “true” in the controller the Visualforce input fields should then default to checked.

      Reply

    • Mickael

      Still don’t know where modifying it to make “Do not create a new opportunity upon conversion” checked. I have modified by the way “false” in “true” but it’s not that.

      Reply

  9. Sujitha

    Hi,

    I like this code its working fine but I don’t want Task information, Description Information and Reminder sections when I convert Lead, I need only convert Lead section when I convert Lead. Can you please suggest me which part of code I have to remove for that.

    Reply

  10. Dave Nelson

    Mike,

    I was very excited about package. I added some customization we needed and it all seemed great, until I realized (as Ralf pointed out,) you can’t link to existing contacts. It is standard functionality and something we really need. What can I do to get this functionality?

    Reply

    • Mike Topalovich

      Hey, Dave. There is a method on the LeadConvert class that allows you to specify a contact ID – off the top of my head I believe it’s just setContactId(Contact.Id). I don’t believe we expose a lookup to Contact in the package, though, although it could be a pretty simple SOSL search and the results could be returned in a SelectList in VF.

      Reply

  11. Vic

    As mentioned previously, how can I get the “Do not create a new opportunity upon conversion” to be checked off by default?

    Reply

    • Dave Nelson

      doNotCreateOppty = Boolean.valueOf(‘True’);

      Put in leadConvertCoreComponentController Apex Class

      Reply

      • Daniel Anthony

        Im very green when it comes to Apex, VF etc. I hack on this stuff until it works or breaks but I can’t figure out how to gheck the box. I believe a modification must be done to this line public Boolean doNotCreateOppty {get; set;} but I do not know what to change it to. I have goe over many sites trying to figure out the syntax but to no avail. If someone could enlighten me it would save a bunch of time. thanks.

        Reply

  12. Yamini Naga Thayaru Bathula

    H Mike,

    i just installed your package in our sandbox. I would like to add some mandatory fields to the visualforce page (if they are not filled in the Lead Detail page. Can you please help me which component I should place these fields?

    Reply

  13. Boris

    Hi Mike,

    I really like this package and I can edit one apex class to fit my needs in my sandbox environment. In a production environment, however, i cannot edit your apex class directly like in a sandbox. What option do you recommend if i need to do these edits? I tried to migrate all components from sandbox to production using change sets but that didn’t wok because there was an apex code failure when validating. I am relatively new to Salesforce so i am wondering how can i edit your apex class in a prod environment after installing the package.

    Thank you very much

    Reply

    • Mike Topalovich

      The process you’ve described is the best…since it’s an unmanaged package you can edit all Apex classes directly, but as you’ve discovered you can only edit in sandboxes or Developer Edition orgs. The unit test code coverage is how Salesforce ensures that code does not blow up in production.

      Reply

  14. Bojan

    Hi Mike,

    Thank you for the package. It works great in a sandbox but when i try to migrate it to production it is giving me 72% code coverage so it doesn’t get deployed. Can you please suggest the best way to bump it up to 75% and over so that it deploys to prod? Thank you

    Reply

    • Mike Topalovich

      The easiest thing would be to run all tests and find classes or triggers that have low code coverage and find any code in the classes not covered (will be highlighted in red). I’m not sure how much code you’re deploying or how much you already have in your org, but it should be hard to find classes that could use additional coverage.

      Reply

  15. RAJESH KUMAR SINGH

    I really like this package and I have edit one visualforce page leadConvertPage i have remove opportunity section from this page but still from backend opportunity is created how i prevent that opportunity not created in my sandbox environment.

    Reply

  16. Danny

    Hi Mike,

    Love the custom convert button. Had a question: I’d like to set the convert feature to only create an account and contact rather than an opportunity. I know there is the Do Not Create An Opportunity button, but is there a way to change the visualforce page to automatically either check the box or just remove the conversion to an opportunity all together.

    Thanks!
    Danny

    Reply

  17. smuraleedharan

    Appreciate if you can also share this in github .

    Reply

  18. Chris Hamman

    Awesome solution! I have needed this in a way I could actually implement myself without a developer for quite sometime – thanks so much! Now, hopefully an easy question….where in the code should I inject input form fields to add other fields that are required by validation rule prior to lead conversion? I’m hoping to add a series of fields to the convert page so people can “quick convert” the lead by filling in all additional lead required fields and then converting. Any advice you can provide is greatly appreciated! Also, checkout gocatalant.com if you are looking for any side / gig-based SFDC consulting work – we source talented folks like you all the time!

    Reply

  19. Marcus

    Very Cool tool.

    I’m not the best with APEX. I’m learning. Question. How would I set the default Opportunity Name in the convert VF page to be the Lead fields Street + ” ” + City + ” ” + State + ” ” PostalCode

    This is a great Blog!

    Reply

  20. Joe Rodden

    One issue we’re running into with it is that we’ve added a few input fields to the actual VF page called from the quick convert button. The idea was to have users input any data that would be required by validation rules on this page rather than having to navigate backwards. The problem we’re having however is that although the information gets entered the convert button doesn’t actually seem to update the lead record before converting so this information doesn’t get saved. Any ideas on how to resolve this?

    Reply

  21. Evan

    This might be a little out there, but I’d like to skip the conversion process and add the button to a contact page, saying “Book Appointment” It would then create an Activity and Related Opportunity on that Contact.

    Possible?

    Reply

    • Mike Topalovich

      Totally doable. Are you in Salesforce Classic or Lightning Experience?

      Reply

      • Evan

        Classic, with no plans to change

        Reply

        • Mike Topalovich

          Shhh…don’t say that out loud! 🙂

          What you’re going to want to do is create a Visualforce page that uses the Contact standard controller with a controller extension. In the apex:page tag, include an “action” attribute that references the name of a method in the Apex class that returns a PageReference. In that method, include logic that creates the new activity record, referencing the Contact’s ID as the WhoId, create a new Opportunity record using Contact.AccountId for the Account ID, save both using a DML operation, and then return the View page for the newly created Opportunity.

          Create a new custom button on the Contact object that references the Visualforce page, add it to the appropriate page layout(s), and you should be good to go.

          Standard caveats – write good unit tests for the Apex class, wrap potential exceptions in a try/catch block, eat your vegetables, etc.

          Reply

          • Evan

            Cough, I mean we are rolling out Lightning slowly… Very slowly…. Awesome! I’ll give it a shot and report back with results. Thanks!

          • Mike Topalovich

            The beauty is this solution will also work in LEX.

  22. Rohan Yadav

    Hi Mike,
    Can you explain the uses of the Components Controller created above ?? The Above description is not descriptive.

    Reply

  23. Rohan Yadav

    The Communication between the leadConvertPage and the Components. Like, we have a VF component ” . Now, i want to know the flow of execution, how the value is being transmitted between Component Controller and VF Page. Moreover, if can state the use of PageControllerBase and ComponentControllerBase.

    Reply

    • topalovich

      Unfortunately it’s been a while since I’ve looked at the package and at this point it’s basically provided as-is. The inline documentation is all the support I can provide.

      Reply

  24. Rohan Yadav

    The Component – ‘c:leadConvertCoreComponent id=”leadComp” thepageController=”{!this}” LeadToConvert=”{!leadToConvert}” rendered=”True” ‘

    Reply

  25. Sahil Nanda

    Hi Mike
    ,
    We are using a custom object (My Lead) instead of Lead object, as the user do not have the access to Lead object.
    How can I modify the code so that we don’t use LeadConvert or if we can pass My_Lead__c.ID instead of Lead.ID for lead conversion process.

    Thanks

    Reply

    • Mike Topalovich

      Using custom objects to replace standard objects is not a good practice and I can’t support such an anti-pattern.

      Reply

Leave a Reply