Offline Lead Conversion

The purpose of this document is to describe MobileCaddy Best Practice regarding the conversion of offline Leads into Accounts, Contacts and Opportunities. Salesforce includes standard functionality on the platform that may be initiated manually from a button on the Lead detail (shown in this TrailHead Module) and offers the ability to achieve the same goal on the platform using the LeadConvert Class with some Convert Leads Considerations. In this document we describe a process that allows the creation of all records (Leads, Accounts, Contacts and Opportunities) to be created and related offline with a Salesforce Conversion taking place following a synchronisation.

Preparation

First of all we need to prepare the Lead standard objects by adding several custom fields. We need to be able to control the relationships between our offline created records and we achieve this by adding the following custom lookup fields on Lead.

  1. MC Opportunity (lookup to Opportunity)
  2. MC Account (lookup to Account)
  3. MC Contact (lookup to Contact)

For each of the above, we need to add the sister proxy field as shown in our Creating Master/Detail and Lookup Relationships document.

Next we need to add a custom picklist field to Lead called ‘MC Conversion Control’. This has values ‘Do Not Convert’, ‘Awaiting’, ‘Converted’, ‘Error’ (set the default value to ‘Do Not Convert’).

NOTE: The 4 new fields above together with the 3 proxy lookup fields must then be mobilised.

The Offline Application

Whenever an offline conversion is required, the application code must create the Account, Contact, Opportunity and Lead. The ids of the Account, Contact and Opportunity must be placed in the relevant lookup fields shown (1, 2 and 3 above). Note the developer does not need to worry whether these are records with Salesforce Id’s or Proxy Id’s, the MobileCaddy sync will handle all scenarios. The ‘MC Conversion Control’ picklist on the Lead must be set to ‘Awaiting’ – this will cause the platform batch apex process (see below) to run on these records following a synchronisation.

Table synchronisation considerations

When looking at Synchronising Leads consider that your user may create leads that are not converted and that they may have earlier created Leads that were converted and therefore have associated Account, Contact and Opportunity records awaiting to sync due to be being offline.

To handle both these scenarios efficiently if you want to sync immediately after locally saving a lead that was not converted make sure your sync services processes the following tables in this order – Account > Contact > Opportunity > Lead (setting syncwithoutlocalupdates to false on Account, Contact and Opportunity).

If you have a sync point after the local Lead conversion process follow the same pattern/order but do not set syncwithoutlocalupdates.

Note if for some reason one of the related Account, Opportunity, Contact records failed to synchronise then the Lead record that references the failing record will not insert/update until the relevant parent record (ie Account, Opportunity, Contact) has been successfully inserted.

The Platform Batch Process

We recommend that a schedulable batch process is created that runs every hour. This will ensure that the processing is disassociated from the MobileCaddy synchronisation process and hence won’t add any extra burden to it.

The batch process will:

  1. Form a query of all Leads with an ‘MC Conversion Control’ set to ‘Awaiting’.
  2. For each lead, create a Database.LeadConvert object. When creating this object call the ‘setAccountId’ and ‘setContactId’ methods with the ids from the lead fields ‘MC Account’ and ‘MC Contact’. Do not call ‘setOpportunityId’ or ‘setOverwriteLeadSource’. Additionally call ‘isDoNotCreateOpportunity’ passing in a value of ‘true’.
  3. Once a list of of these objects has been created, call the bulkified version of the convertLead call. Set the ‘allOrNone’ parameter to false.
  4. The return parameter from the above call will be a list of LeadConvertResult objects. You may cycle through these calling ‘isSuccess’ to check if there were any failures or not. Additionally you may call ‘getErrors’ to determine the exact nature of any failures.
  5. For each successful call, update the ‘MC Conversion Control’ on the corresponding Lead to ‘Converted’.
  6. For each failure, update the ‘MC Conversion Control’ on the corresponding Lead to ‘Error’.
  7. Optional Step – Create a workflow rule on the ‘MC Conversion Control’ to notify users of success / error conversions.
  8. Before migration to production, Apex Test Methods must be written. The tests will need to (at a minimum) create a Lead, Account, Contact and Opportunity record with the lookups from Lead filled in and the ‘MC Conversion Control’ set to ‘Awaiting’.

Limitations

The following are limitations – ie features that may be available during an online manual conversion / custom Apex platform solution that are not available when performing offline conversions as recommended in this document.

  • Using the above method will result in the linking/merging of the Lead to Account and/or Contact. It is not possible to pass in an Opportunity record for linking/merging. However the custom Opportunity lookup on the Lead (if populated in the mobile code) will be available to report on. Note this is a Salesforce limitation.
  • When field mappings are setup on the platform for Lead Conversion, this underlying metadata is not available on the device. If one or more of these mappings is required when creating the offline converted records then this must be written explicitly into the mobile application code too. Note that following a synchronisation, Account and Contact mappings will be copied across provided that the destination fields are blank. Note – Opportunity mappings will not be copied due to the Salesforce limitation of not being able to pass an existing Opportunity Id in to the merge/convert Apex code.