CRM Lead Management — business view

Technical trace: CRM Lead Management

1. Business Summary

Captures prospects from many channels (manual entry, FreshSales sync, Cognito web forms, partner-platform onboarding), qualifies them through a multi-step lifecycle, and converts qualified leads into customer accounts.

2. Business Value

Pipelines prospects into customers; lets sales attribute revenue back to source/campaign; reduces lost leads.

3. Users / Stakeholders

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

4. Workflows

  • Lead intake. Trigger: manual entry or external sync. Steps: a Lead is created with source, industry, campaign, qualification status, status, rating, and addresses. Result: Lead record visible to its owner. Exception: Mandatory fields missing (qualifier, address) block save.
  • Qualification. A lead qualifier reviews the lead, optionally requests more leads from a request-for-leads queue with targeting filters (region, industry, company size, certificate, membership), and updates the lead's qualification status.
  • Conversion to Account. Qualified leads become Accounts and inherit attribution. Activities and cases stay linked.

5. Sub-Features

  • Source tracking, ratings, qualification status.
  • Sales-campaign-driven request-for-leads with targeting filters.
  • FreshSales sync.
  • Lead-to-account conversion.

6. Business Rules

  • Primary address and qualifier are required.
  • Qualification status drives conversion eligibility.
  • The FreshSales sync is destructive — it overwrites local copies in full.

7. Data Entities

Lead, Lead Status, Qualification Status, Account Source, Database, Rating, Marketing Campaign, Sales Campaign, Request For Leads, Industry, Address, Country/State/Region.

8. Entry Points

  • CRM web pages (leads, requests for leads, sales campaigns).
  • FreshSales sync (scheduled).
  • Cognito Forms (recruitment-style intake).

9. Inputs & Outputs

  • Inputs: lead data, source, address, qualification information.
  • Outputs: Lead records, activities, cases, account conversions.

10. Integrations

  • FreshSales (marketing CRM).
  • Cognito Forms (web intake).
  • Email notifications.

11. Calculations / Logic

  • No financial logic; rating-based prioritization is informational.

12. Status Lifecycle

  • Lead: new → contacted → qualified → converted/lost.
  • Qualification: qualified / not qualified / needs more info.
  • Request-for-leads: open → in-progress → fulfilled / cancelled.

13. Permissions

  • Owner via "created by", qualifier via assignment, brand isolation post-conversion.

14. Reports & KPIs

  • Source mix, qualification rate, conversion rate, time-to-qualify, FreshSales-imported attributes.

15. Risks & Observations

  • Hard-coded API token for FreshSales.
  • Destructive full-replace sync — risk of data loss if the API call fails partway.
  • No automatic deduplication on conversion — duplicate accounts possible.
  • Custom-field flattening on FreshSales import is sensitive to upstream schema changes.

16. Source Code Evidence

  • app/Plugin/crm/Controller/{LeadsController, RequestsForLeadsController, SalesCampaignsController, FreshSalesController}.php.

← Deep dives index