Prelead Management Use Cases (PRE)¶

Module Purpose: Manage high-volume raw data from campaigns, directories, and email integrations before they qualify as CRM leads.

Use Case Quick Reference¶

ID	Title	Priority
US-PRE-001	Raw Data Ingestion	P1
US-PRE-002	3-Level Screening	P1
US-PRE-004	De-duplication Logic	P1
US-PRE-004	Raw-to-Recheck Mapping	P1
US-PRE-005	Transfer to BD / Mapped User	P1
US-PRE-006	Performance Alerts (Screening Variance)	P2
US-PRE-007	The 11:30 AM Rule (Auto-Shift)	P1
US-PRE-008	Call Execution & Follow-up Logic	P1
US-PRE-010	Validator "Man-in-the-loop" Workflow	P1
US-PRE-009	Route Planning & Field Visits	P2

US-PRE-001: Raw Data Ingestion (Excel/API)¶

Purpose: Accept and process high-volume raw prelead data from Excel uploads, Outlook integration, and third-party APIs (IndiaMart, TradeIndia) into the Raw Prelead bucket for downstream screening.

Property	Value
Actor	Back-office Team, System Integration Engine
Trigger	User uploads Excel file OR Outlook folder sync interval (every 15 min) OR API webhook
Preconditions	- Excel template matches defined schema - Outlook OAuth token valid - API credentials configured
Priority	P1

Main Success Scenario (Excel Ingestion)¶

Upload Initiation
User selects Excel file via file picker. System validates .xlsx/.csv format.
System displays Column Mapper UI.
User maps: Buyer Name, Address, Mobile, Email, Product Name, Source Details.
Auto-Fill & Field Mapping
System parses data and auto-fills missing fields using AI (from snapshots) or existing Master data.
For Directories: System requires Product, Customer, Contact, Directory Name, Source, Vendor.
For Database: System requires Industry, Source Master, Name of Database, Links.
Row Selection Screen
System displays a grid of parsed rows.
User selects specific checkboxes for rows they want to "Generate Preleads" for.
User clicks "Generate".
Creation of Raw Preleads
System creates records with status = "Raw".
Auto-generates subject: [Customer Name] + [Product Name].
Records include a snapshot/screenshot of the original data row/email for verification.

Outlook Integration (Enquiry Extraction)¶

Enquiry Polling
System auto-pulls emails from the integrated Outlook inbox.
For each email, system parses content and auto-fills Buyer, Mobile, Product, etc.
Attachment/Snapshot of the email is captured in the Raw Prelead view.
Approval Gate for Existing Targets
If the ingested record matches an existing Customer Master:
- System flags the record for Approval Gate.
- Request is sent to the Owner tagged to that customer before any quote can be sent.

Alternative Flows¶

A1: Duplicate File Upload - At step 1, if file hash (MD5) matches existing upload within 24h - System shows warning: "This file was uploaded X hours ago" - User can proceed or cancel

A2: Column Mismatch - At step 2, if required columns missing (Buyer Name OR Mobile/Email) - System blocks upload, highlights missing columns in red

A3: Outlook Sync Failure - At step 1, if OAuth token expired - System triggers re-authentication flow via popup - User re-authorizes, sync resumes

Observability¶

Metrics:

prelead_uploads_total{source="excel|outlook|api", status="success|failed"}
prelead_records_created{source="excel|outlook|api"}
prelead_validation_errors{field="email|phone|name"}

Logs:

{
  "event": "prelead_batch_uploaded",
  "user_id": "user_123",
  "source": "excel",
  "file_name": "campaign_leads_jan.xlsx",
  "rows_total": 450,
  "rows_valid": 442,
  "rows_invalid": 8,
  "duration_ms": 1200
}

Acceptance Criteria¶

Processes Excel files up to 10MB / 5000 rows
Supports concurrent uploads (up to 10 users)
Captures email snapshots within 2 seconds
Auto-generates subject for 100% of records
Flags validation errors without blocking upload
Links all attachments (PDF, JPG, email) to Prelead ID
Emits batch creation event for downstream processing
Handles Outlook OAuth refresh automatically

US-PRE-002: 3-Level Screening Workflow¶

Purpose: Validate raw preleads through a progressive 3-tier screening process (Level 1 → Level 2 → Level 3) with quality control alerts to ensure only high-quality leads reach sales teams.

Property	Value
Actor	Marketing Screening Team, Quality Control Manager
Trigger	Prelead moves to "Raw" status OR screening level fails
Preconditions	- Prelead exists with status = "Raw" - Screening team members assigned to levels - Performance thresholds configured
Priority	P1

Main Success Scenario¶

Level 1: Fresh Validation
Screener opens Prelead from Level 1 Queue
Screener verifies: Company name is real, Product is valid, Contact info looks legitimate
Screener selects outcome: "Qualified" OR "Not Qualified"
If "Qualified": Prelead moves to Approval Queue
If "Not Qualified": Prelead moves to Level 2 Queue
Level 2: Re-check & Deep Validation
Different screener opens Prelead from Level 2 Queue
System shows Level 1 screener's name and reason for rejection
Screener performs deeper validation: Google search company, verify domain registration, check social profiles
Screener selects outcome: "Qualified" OR "Not Qualified"
If "Qualified": Prelead moves to Approval Queue (with flag: "Level 2 Recovery")
If "Not Qualified": Prelead moves to Level 3 Queue
Level 3: Final Escalation
Manager/Senior Screener reviews Prelead from Level 3 Queue
System shows both Level 1 and Level 2 screener names and reasons
Manager makes final decision: "Qualified" OR "Drop"
If "Qualified": Prelead moves to Approval Queue (with flag: "Level 3 Escalation")
If "Drop": Prelead status set to "Rejected", archived
Quality Analytics Trigger
System calculates screening variance: (Level 2 Recoveries / Level 1 Rejections) * 100
If variance > 30% for a specific screener in a day:
- System emits alert: screening.quality.variance_high
- Email sent to Manager: "Screener X has high variance (45%), review needed"

Alternative Flows¶

A1: Underperformance Alert - During Level 1, if screener processes < 10 preleads/hour for 2 consecutive hours - System triggers alert: screening.performance.low - Manager receives notification

A2: Batch Qualification - At any level, if screener selects multiple preleads (bulk action) - System applies same decision to all - System logs: bulk_decision_applied: {count: 50, decision: "qualified"}

Observability¶

Metrics:

prelead_screening_decisions_total{level="1|2|3", decision="qualified|rejected"}
prelead_screening_duration_seconds{level="1|2|3"}
prelead_screening_variance_percent{screener_id="user_X"}
prelead_queue_depth{level="1|2|3"}

Logs:

{
  "event": "prelead_screening_completed",
  "prelead_id": "PRE-20260108-00123",
  "level": 1,
  "screener_id": "user_45",
  "decision": "not_qualified",
  "reason": "Invalid company – no web presence",
  "duration_seconds": 45
}

Acceptance Criteria¶

Prelead cannot skip levels (must go 1 → 2 → 3 sequentially)
Each level is assigned to different screeners (no self-review)
Variance alert triggers if Level 2 recoveries exceed 30% for any screener
Underperformance alert triggers if < 10 preleads/hour for 2 hours
Manager can view historical screening decisions for training purposes
Queue depth visible in real-time dashboard

US-PRE-003: Source Attribution & Database Naming¶

Purpose: Capture and categorize the source of each prelead (Campaign, Directory, Database, Referral) with source-specific metadata fields to enable accurate ROI tracking and lead quality analysis by channel.

Property	Value
Actor	Back-office User, System
Trigger	During prelead creation (PRE-001) OR manual edit
Preconditions	- Source type picklist configured - Directory/Database masters exist
Priority	P1

Main Success Scenario¶

Source Type Selection
User selects Lead Source from dropdown:
- Campaign (Marketing/PRD/Industries)
- Directory (Business directories)
- Database (Old/New/Purchased)
- Referral (Employee/Field Visit)
System dynamically shows relevant fields based on selection
Campaign Source
If source = "Campaign":
- System shows: Campaign Name (dropdown from Campaign master)
- System shows: Industry (picklist: Pharma, Chemicals, Food, etc.)
- System shows: Product Category (multi-select)
User selects campaign: "Zinc Oxide Q1 2026"
System auto-tags prelead with campaign ID for ROI tracking
Directory Source
If source = "Directory":
- System shows: Directory Name (text field)
- System shows: Directory Type (picklist: India Mart, Trade India, Alibaba, etc.)
- System shows: Vendor Name (who we purchased from)
User enters: "India Mart", "Trade India Platform", "Vendor XYZ"
Database Source
If source = "Database":
- System shows: Database Name (text field)
- System shows: Database Type (picklist: Old/New/Purchased)
- System shows: Industry (picklist)
User enters: "Chemical Buyers DB 2025", "Purchased", "Chemicals"
Referral & Field Visit
If source = "Referral" or "Field Visit":
- System shows: Employee Name (Referrer).
- For Field Visit: Captures Route Planning data (Cross-ref: US-PRE-009).
Source Metadata Storage
System saves all source-specific fields to prelead record
System increments counter: source_stats.campaign_X.leads_generated++
Data available for reporting: "Leads by Source", "ROI by Campaign"

Observability¶

Metrics:

prelead_sources_total{source_type="campaign|directory|database|referral"}
prelead_campaign_performance{campaign_id="camp_123", status="qualified|rejected"}

Logs:

{
  "event": "prelead_source_attributed",
  "prelead_id": "PRE-20260108-00999",
  "source_type": "campaign",
  "source_details": {
    "campaign_name": "Zinc Oxide Q1 2026",
    "industry": "Pharma",
    "product_category": ["Zinc Oxide", "Magnesium Oxide"]
  }
}

Acceptance Criteria¶

Dynamic field rendering based on source type selection
Campaign dropdown populated from Campaign master
Directory/Database fields allow free-text entry
Employee dropdown populated for Referral source
Source metadata stored in structured JSON field
Enables reporting by source type and specific source
Cross-links Field Visit referrals to Route Planning (EML-014)

US-PRE-004: Raw-to-Recheck Mapping (De-dupe)¶

Purpose: Automatically detect and flag potential duplicate preleads by matching phone numbers, email domains, and company identifiers (CIN/PAN) against existing customer and contact masters to prevent redundant data entry.

Property	Value
Actor	System De-duplication Engine, Validation APIs
Trigger	Prelead moves from "Raw" status to "Re-check" queue
Preconditions	- Customer/Contact masters populated - RocketReach API key configured - Phone validation service active
Priority	P1

Main Success Scenario¶

Prelead Entry to Re-check Queue
System retrieves prelead from Level 1 screening queue
System extracts key fields: phone, email, company_name, domain
Phone Number Matching
System queries Contact master: SELECT * WHERE phone = prelead.phone
If match found (exact 10-15 digit match):
- System displays: "⚠️ This phone (91-XXXXXXXXXX) is mapped to Contact Name at Company ABC"
- System shows contact's full profile + transaction history
If no match: Proceed to step 3
Email Domain Matching
System extracts domain from email: user@domain.com → domain.com
System queries Customer master: SELECT * WHERE email_domain = 'domain.com'
If match found:
- System displays: "⚠️ This domain belongs to Company ABC (CID: CUST-12345)"
- System suggests: "Link as Same Customer or Group Company?"
If no match: Proceed to step 4
CIN/PAN Similarity Check (Cross-link to US-EML-013)
If prelead has CIN or PAN in notes/attachments:
- System calls fuzzy match service: similarity(prelead.cin, master.cin) >= 95%
- If similar CIN/PAN found:
- System blocks: "🛑 Duplicate detected – CIN matches Company XYZ"
- System requires manager override to proceed
Email Validation via RocketReach
System calls RocketReach API: validate_email(prelead.email)
API returns: {valid: true, deliverable: true, company: "ABC Corp"}
If email invalid: Flag prelead with "Email validation failed"
Consolidation & Flagging
System creates De-dupe Report attached to prelead:
- Matched contacts (if any)
- Matched customers (if any)
- Validation status (phone valid, email valid)
System updates prelead status: "Re-check – Matches Found" OR "Re-check – No Matches"

Alternative Flows¶

A1: Multiple Phone Matches - At step 2, if phone matches 2+ contacts (e.g., shared office line) - System displays all matches in dropdown - Screener selects primary contact manually

A2: Domain Match with Group Company - At step 3, if domain matches existing customer - Screener can tag as "Group Company" instead of "Same Customer" - System links both entities under Group hierarchy (Cross-ref: US-MST-001)

A3: RocketReach API Timeout - At step 5, if API call takes > 5 seconds - System skips email validation, logs warning - Prelead proceeds with flag: "Email validation pending"

Observability¶

Metrics:

prelead_dedup_checks_total{match_type="phone|domain|cin"}
prelead_dedup_matches_found{match_type="phone|domain|cin"}
prelead_email_validation_calls{status="success|failed|timeout"}
prelead_dedup_duration_seconds

Logs:

{
  "event": "prelead_dedup_completed",
  "prelead_id": "PRE-20260108-00456",
  "phone_matches": 1,
  "domain_matches": 1,
  "cin_matches": 0,
  "email_valid": true,
  "duration_ms": 850
}

Acceptance Criteria¶

Checks phone against all contact records (exact match)
Checks email domain against all customer records
Performs CIN/PAN fuzzy match at 95% similarity threshold
Blocks duplicate creation if CIN match above threshold
Integrates with RocketReach for email validation
Displays all matches with full context (contact name, company, history)
Allows manual override with manager approval
Completes de-dupe check within 2 seconds (excluding external API calls)

US-PRE-005: Transfer to BD / Mapped User¶

Purpose: Automatically detect when a prelead's customer is already assigned to an existing sales user and trigger an approval workflow to either transfer ownership, allow dual-handling, or drop the duplicate prelead.

Property	Value
Actor	System Workflow Engine, Mapped User (Owner), Prelead User
Trigger	Prelead passes de-dupe check AND customer master has `assigned_user_id` populated
Preconditions	- Customer master exists with active owner - Prelead user has permission to request transfers - Notification service configured
Priority	P2

Main Success Scenario¶

Ownership Conflict Detection
During PRE-004 de-dupe, system identifies customer match: "Company ABC"
System checks Customer master: assigned_user_id = user_123 (Sales Rep: John Doe)
System compares: prelead.created_by = user_456 (Marketing Rep: Jane Smith)
Conflict detected: Prelead user ≠ Customer owner
Transfer Request Creation
System creates Transfer Request record:
- prelead_id: PRE-20260108-00789
- requesting_user: user_456 (Jane)
- target_user: user_123 (John)
- status: "Pending Approval"
System emits notification: transfer.request.created
Owner Notification

System sends email + in-app notification to John:

Subject: Transfer Request for Company ABC

Jane Smith wants to work on a prelead for **Company ABC** (your customer).

Prelead Details:
- Product: Zinc Oxide
- Source: India Mart
- Contact: contact@companyabc.com

Actions: [Approve] [Transfer to Me] [Drop]

Owner Decision - Approval Path
John clicks [Approve]
System updates:
- Prelead status: "Approved – Dual Handling"
- Prelead owner remains: user_456 (Jane)
- Prelead field assistant_user_id: user_123 (John) – receives CC on all updates
Jane can proceed with quote
Owner Decision - Transfer Path
John clicks [Transfer to Me]
System updates:
- Prelead owner: user_123 (John)
- Prelead field assistant_user_id: user_456 (Jane) – receives CC, can assist
- Notification sent to Jane: "Prelead transferred to John, you're added as Assistant"
John takes over quote process
Owner Decision - Drop Path
John clicks [Drop] + enters reason: "Duplicate enquiry from last week"
System updates:
- Prelead status: "Rejected – Owner Veto"
- Prelead archived, Jane cannot proceed
Jane receives notification with rejection reason

Alternative Flows¶

A1: No Response from Owner (72 hours) - At step 3, if John doesn't respond within 72 hours - System auto-escalates to John's Manager - Manager can approve/transfer/drop - If manager also doesn't respond in 24h: Auto-approve (Jane proceeds)

A2: Owner on Leave - At step 1, if John's status = "On Leave" - System checks for temporary_owner (e.g., John's backup: user_789) - Transfer request sent to backup user - Original approval workflow applies

A3: Prelead User Requests Drop - Before reaching this UC, Jane can voluntarily drop the prelead if she sees it matches existing customer - No approval needed, prelead auto-archived

Observability¶

Metrics:

prelead_transfer_requests_total{decision="approve|transfer|drop|timeout"}
prelead_transfer_request_duration_seconds
prelead_assistant_assignments_total

Logs:

{
  "event": "transfer_request_decided",
  "prelead_id": "PRE-20260108-00789",
  "requesting_user": "user_456",
  "target_user": "user_123",
  "decision": "approve",
  "decider": "user_123",
  "duration_hours": 2.5
}

Acceptance Criteria¶

Detects ownership conflict if customer has assigned_user_id
Creates transfer request with all context (product, source, contact)
Sends notification to mapped user within 30 seconds
Supports 3 decision paths: Approve, Transfer, Drop
Assigns Assistant role correctly based on decision
Auto-escalates to manager if no response in 72 hours
Auto-approves if manager also doesn't respond in 24 hours
Handles owner on leave by routing to temporary_owner

US-PRE-006: Performance Alerts (Screening Variance)¶

Purpose: Monitor screening quality by detecting variance between Level 1 and Level 2 decisions, and employee productivity by tracking screening throughput, triggering management alerts when thresholds are breached.

Property	Value
Actor	System Analytics Engine, Quality Control Manager
Trigger	End of day batch job (runs at 11:59 PM) OR real-time after every 50 screening decisions
Preconditions	- Screening decisions logged in database - Performance thresholds configured - Manager notification emails set up
Priority	P2

Main Success Scenario¶

Daily Analytics Aggregation
At 11:59 PM, system queries screening decisions for the day
System groups by screener: user_45, user_67, user_89
For each screener, system calculates:
- Level 1 rejections: COUNT(level=1, decision='rejected')
- Level 2 recoveries: COUNT(level=2, decision='qualified') of preleads they rejected at L1
- Variance: (L2_recoveries / L1_rejections) * 100
Variance Threshold Check
System checks if variance > 30% for any screener
Example: user_45 rejected 100 preleads at L1, but 45 were qualified at L2 → 45% variance
If variance > 30%:
- System creates Alert: screening.quality.variance_high
- Alert severity: "Warning" (30-50%), "Critical" (>50%)
Productivity Threshold Check
System calculates hourly throughput: preleads_screened / hours_worked
If throughput < 10 preleads/hour for 2+ consecutive hours:
- System creates Alert: screening.performance.low
- Alert severity: "Warning"
Manager Notification

System sends email to Quality Control Manager:

Subject: [Alert] Screening Quality Issue – User 45

**Variance Alert**:
- Screener: Jane Doe (user_45)
- Level 1 Rejections: 100
- Level 2 Recoveries: 45
- **Variance: 45%** (Threshold: 30%)

**Recommended Action**: Review training materials with Jane

[View Detailed Report]

Alert Dashboard Update
System updates real-time dashboard widget:
- Today's Variance Alerts: 2
- Week's Productivity Alerts: 5
- Trend graph: Variance by screener over 30 days
Historical Tracking
System stores alert in performance_alerts table
Manager can view historical alerts and resolution notes
Used for quarterly performance reviews

Alternative Flows¶

A1: Real-time Alert (50 Decision Trigger) - Instead of waiting until EOD, system checks variance after every 50 decisions - If real-time variance > 40%: Immediate alert to manager - Allows for same-day intervention

A2: Consecutive Days Above Threshold - If screener has variance > 30% for 3 consecutive days - Alert escalates to Senior Management - Suggests formal retraining or role reassignment

Observability¶

Metrics:

prelead_screening_variance_percent{screener_id="user_X", period="daily|weekly"}
prelead_screening_throughput_per_hour{screener_id="user_X"}
prelead_performance_alerts_fired{alert_type="variance|productivity", severity="warning|critical"}

Logs:

{
  "event": "performance_alert_fired",
  "alert_type": "screening_variance",
  "screener_id": "user_45",
  "screener_name": "Jane Doe",
  "l1_rejections": 100,
  "l2_recoveries": 45,
  "variance_percent": 45,
  "threshold_percent": 30,
  "severity": "critical",
  "notified_manager": "manager_01"
}

Acceptance Criteria¶

Calculates variance as (L2 recoveries / L1 rejections) * 100
Triggers alert if variance > 30%
Calculates hourly throughput automatically
Triggers alert if throughput < 10 preleads/hour for 2+ hours
Sends email notification to manager with context
Updates real-time dashboard with alert count
Stores historical alerts for reporting
Escalates to senior management after 3 consecutive days above threshold

US-PRE-007: The 11:30 AM Rule (Auto-Shift)¶

Purpose: Ensure operational continuity if an employee is absent or late by automatically shifting high-priority prelead work to temporary owners or management tiers.

Property	Value
Actor	System Scheduler, Temporary Owner, HOD, Management
Priority	P1

Main Success Scenario¶

Login Deadline Check
At 11:30 AM daily, system checks user login status.
If user has NOT logged in:
- All active/high-priority Preleads are flagged for "Auto-Shift".
Work Shifting
System reassigns tasks to:
- Path A: Dedicated Temporary Owner (pre-configured).
- Path B: (If A absent) HOD (Head of Department).
- Path C: (If B absent) Management.
User Recall
When the original user eventually logs in:
- System shows a "Recall All Work" button.
- User can click to pull back all shifted tasks that have not yet been processed by the backup owner.

US-PRE-008: Call Execution & Follow-up Logic¶

Purpose: Automate the lead-nurturing cadence based on real-world communication outcomes.

Property	Value
Actor	System, Prelead User
Priority	P1

Main Success Scenario¶

Call Outcome Logging
User logs call result: "No Answer / Busy".
Auto-Cadence Trigger
System auto-generates a follow-up task:
- Immediately: Send standardized Email or WhatsApp message.
- In 2 Hours: Schedule "Next Call" reminder.
Discussion History
System maintains sequential logs: Call 1, Call 2, Call 3... with timestamps and specific party feedback.

US-PRE-009: Route Planning & Field Visits¶

Purpose: Optimize field visit productivity by grouping potential targets geographically.

Property	Value
Actor	Field Sales, System
Priority	P2

Main Success Scenario¶

Pincode Route Planning
User enters a target Pincode.
System plots a route based on proximity.
Locality Discovery
System identifies and displays all Suppliers and Customers within that specific locality.
User can batch-add these as "Cold Visits" to the current campaign route.

US-PRE-010: Validator "Man-in-the-loop" Workflow¶

PHASE: 1 (MOM Jan 27 Agreement)

Purpose: Provide a dedicated interface for the manual validation of master data extracted by AI, ensuring 100% accuracy before records become "active" in the CRM.

Validator Responsibilities¶

Resolve Duplicates: Merge records with typos (e.g., "MFP" vs "MFP Industries") or full-name variations.
Data Enrichment: Verify company legitimacy, CIN, and GST numbers using online portals.
Master Linking: Correctly link Account, Product, and Contact masters.
Scoring: Manually escalate/de-escalate internal customer scores based on verified business potential.

UI Features¶

Diff View: Side-by-side comparison of AI-extracted data vs existing master data.
One-Click Merge: Transfer selected fields from an incoming inquiry to an existing Golden Record.
Verification Direct Links: Buttons to open GST/MCA portal with pre-filled ID.

← Back to Use Cases

Prelead Management Use Cases (PRE)¶

Use Case Quick Reference¶

US-PRE-001: Raw Data Ingestion (Excel/API)¶

Main Success Scenario (Excel Ingestion)¶

Outlook Integration (Enquiry Extraction)¶

Alternative Flows¶

Observability¶

Acceptance Criteria¶

US-PRE-002: 3-Level Screening Workflow¶

Main Success Scenario¶

Alternative Flows¶

Observability¶

Acceptance Criteria¶

US-PRE-003: Source Attribution & Database Naming¶

Main Success Scenario¶

Observability¶

Acceptance Criteria¶

See Also¶

US-PRE-004: Raw-to-Recheck Mapping (De-dupe)¶

Main Success Scenario¶

Alternative Flows¶

Observability¶

Acceptance Criteria¶

See Also¶

US-PRE-005: Transfer to BD / Mapped User¶

Main Success Scenario¶

Alternative Flows¶

Observability¶

Acceptance Criteria¶

See Also¶

US-PRE-006: Performance Alerts (Screening Variance)¶

Main Success Scenario¶

Alternative Flows¶

Observability¶

Acceptance Criteria¶

See Also¶

US-PRE-007: The 11:30 AM Rule (Auto-Shift)¶

Main Success Scenario¶

US-PRE-008: Call Execution & Follow-up Logic¶

Main Success Scenario¶

US-PRE-009: Route Planning & Field Visits¶

Main Success Scenario¶

US-PRE-010: Validator "Man-in-the-loop" Workflow¶

Validator Responsibilities¶

UI Features¶