CRM Lead Management

Business perspective: CRM Lead Management

1. Business Summary

Captures leads from multiple sources (web, FreshSales, Cognito, Welocalize accounts), qualifies them via status/rating/qualification, links to campaigns, and converts them into Accounts.

2. Business Value

Pipelines prospects into customers; enables source-attributed sales analysis.

3. Users / Stakeholders

Sales agents, lead qualifiers, marketing, sales operations, sales managers.

4. Workflows

A. Lead intake
- Triggers: manual entry, FreshSales import (FreshSalesController::FreshSalesLead), Welocalize-style account onboarding.
- Steps: create Lead with lead_source_id, industry_id, marketing_campaign_id, qualification_status_id, lead_status_id, database_id, rating_id and addresses.
- Outputs: Lead record + Activity/Case threads.

B. Qualification
- Lead Qualifier (assigned via lead_qualifier_id on RequestForLead) reviews lead.
- Status moves through LeadStatus and QualificationStatus.
- May request more leads via RequestForLead filters (Region/Country/State/Industry/CompanySize/Membership/Certificate).

C. Conversion to Account
- Lead → Account (Account.lead_id FK references the originating lead).
- Activities/Cases on the lead remain linked.

5. Sub-Features

  • Lead source tracking, rating, qualification status.
  • Sales campaigns linked to RequestForLead filters.
  • FreshSales sync (full replace import).
  • Lead-to-Account conversion.
  • Marketing campaign attribution.

6. Business Rules

  • Required fields: primary_address_id, created_by/modified_by, lead_qualifier_id (on RequestForLead).
  • Lead.qualification_status_id drives downstream conversion eligibility.
  • FreshSales import uses TRUNCATE on local sync tables before reload (destructive without backup).

7. Data Entities

Lead, LeadStatus, QualificationStatus, AccountSource, Database, Rating, MarketingCampaign, SalesCampaign, RequestForLead, RequestForLeadsLead, RequestsForLead, Industry, Address, Country/State/Region/SubRegion.

8. Entry Points

  • Web: crm/leads, crm/requestsForLeads, crm/salesCampaigns.
  • Cron/API: FreshSalesController::FreshSalesLead.
  • Webhook: cognito/base for some lead/applicant flows.

9. Inputs & Outputs

  • Inputs: lead data, source, address, qualification info.
  • Outputs: Lead record, Activities, Cases, conversion to Account.

10. Integrations

  • FreshSales (token JzGsLSRqLVTg2akBpPrujA hard-coded).
  • Cognito (forms).
  • Email (notifications via WebServices/EntityThread).

11. Calculations / Logic

None financial; rating-based prioritization is informational.

12. Status Lifecycle

  • LeadStatus (e.g., new → contacted → qualified → converted/lost).
  • QualificationStatus (qualified / not qualified / needs more info).
  • RequestForLeadsStatus tracks request fulfillment.

13. Permissions

  • Owner via created_by, qualifier via lead_qualifier_id.
  • Brand isolation via FreshSales mapping & Account.brand_id when converted.

14. Reports & KPIs

  • Source mix, qualification rate, conversion rate.
  • FreshSales-imported metrics (custom fields like cf_brand_1_last_sale_date).

15. Risks & Observations

  • Hard-coded FreshSales API token.
  • TRUNCATE on full sync — risk of data loss if API fails mid-import.
  • Custom fields flattened into models; schema drift risk if FreshSales fields change.
  • No deduplication logic at conversion (potential duplicate accounts).

16. Source Code Evidence

  • app/Plugin/crm/Controller/LeadsController.php, RequestsForLeadsController.php, SalesCampaignsController.php.
  • app/Plugin/crm/Model/Lead.php, RequestForLead.php, RequestForLeadsStatus.php.
  • app/Plugin/crm/Controller/FreshSalesController.php :: getFreshSalesData, FreshSalesLead, getOwners, getAccounts, getCampaigns.

← Deep dives index