🤝 Deals & CRM Processing

📖 Overview

The Deals module handles CRM deal imports and automated workflow execution for deal management.

Environment Flags:

• QM_DEALS=true - Deal import processing
• QM_DEALS_AUTOMATIONS=true - Deal automation workflows

Source Location: queue-manager/crons/deals/

Processing Pattern: High-frequency polling (every 5-30 seconds)

🗄️ Collections Used

deal

• Operations: Create/Update
• Model: shared/models/deal.js
• Usage: CRM deal records

pipeline

• Operations: Read
• Model: shared/models/pipeline.js
• Usage: Sales pipeline configurations

automation

• Operations: Read
• Model: shared/models/automation.js
• Usage: Automation workflow definitions

automation-log

• Operations: Create
• Model: shared/models/automation-log.js
• Usage: Track automation execution

🔄 Processing Flow

graph TB
    API[Internal API] -->|Create Import Job| QUEUE[Import Queue]

    IMPORT_CRON[Import Cron<br/>Every 5s] -->|Query| QUEUE
    AUTO_CRON[Automations Cron<br/>Every 30s] -->|Query| TRIGGERS[(Automation Triggers)]

    IMPORT_CRON -->|Process| IMPORT_SVC[Import Service]
    AUTO_CRON -->|Execute| AUTO_SVC[Automation Service]

    IMPORT_SVC -->|Parse CSV| DEALS[(Deals)]
    IMPORT_SVC -->|Map Fields| CUSTOM_FIELDS[Custom Fields]
    IMPORT_SVC -->|Insert| DEALS

    AUTO_SVC -->|Match Conditions| DEALS
    AUTO_SVC -->|Execute Actions| ACTIONS[Actions]
    ACTIONS -->|Update Deal| DEALS
    ACTIONS -->|Send Email| EMAIL[Email Service]
    ACTIONS -->|Create Task| TASKS[(Tasks)]
    ACTIONS -->|Webhook| EXTERNAL[External API]

🔧 Jobs in This Module

Core Jobs

• 📘 Import - Bulk deal imports from CSV
• 📗 Automations - Automated workflow execution

⚙️ Configuration

Required Environment Variables:

QM_DEALS=true                       # Enable deal imports
QM_DEALS_AUTOMATIONS=true           # Enable deal automations

MONGO_DB_URL=...
REDIS_HOST=localhost
REDIS_PORT=6379

---

📘 Deal Import

Overview

Processes bulk deal imports from CSV files with field mapping and validation.

Cron Schedule: */5 * * * * * (Every 5 seconds)

Source Files:

• Cron: queue-manager/crons/deals/import.js
• Service: queue-manager/services/deals/import.js

Processing Flow

sequenceDiagram
    participant API as Internal API
    participant QUEUE as Import Queue
    participant CRON as Import Cron
    participant SERVICE as Import Service
    participant DB as MongoDB

    API->>QUEUE: Create import job<br/>(CSV file, field mapping)

    loop Every 5 seconds
        CRON->>SERVICE: Execute
        SERVICE->>QUEUE: Query pending imports
        QUEUE-->>SERVICE: Pending jobs
        SERVICE->>SERVICE: Download & parse CSV
        SERVICE->>SERVICE: Map fields to deal schema
        SERVICE->>SERVICE: Validate deals
        SERVICE->>DB: Bulk insert deals
        SERVICE->>QUEUE: Update status<br/>(imported, failed counts)
    end

Key Features

• CSV Import: Support for standard CSV formats
• Field Mapping: Flexible column-to-field mapping
• Custom Fields: Import into custom deal fields
• Duplicate Detection: Check for existing deals by email/name
• Pipeline Assignment: Auto-assign to correct pipeline stage
• Owner Assignment: Assign deals to team members
• Validation: Deal value, stage, contact validation
• Bulk Operations: Efficient batch processing

Import Options

Field Mapping:

• Required: Deal name, contact email, pipeline
• Optional: Deal value, stage, owner, custom fields
• Flexible column names

Duplicate Handling:

• Skip duplicates
• Update existing deals
• Create as new deals

Pipeline Rules:

• Default pipeline assignment
• Stage-based routing
• Auto-stage progression

Error Handling

Row-Level Errors:

• Invalid email format
• Missing required fields
• Invalid pipeline/stage
• Duplicate detection

Import Results:

• Total rows processed
• Successfully imported
• Failed imports with reasons
• Updated existing deals

---

📗 Deal Automations

Overview

Executes automated workflows triggered by deal events and conditions.

Cron Schedule: */30 * * * * * (Every 30 seconds)

Source Files:

• Cron: queue-manager/crons/deals/automations.js
• Service: queue-manager/services/deals/automations.js

Processing Flow

sequenceDiagram
    participant CRON as Automations Cron
    participant SERVICE as Automation Service
    participant DB as Deals
    participant AUTO as Automations
    participant ACTION as Action Executor

    loop Every 30 seconds
        CRON->>SERVICE: Execute
        SERVICE->>AUTO: Query active automations
        AUTO-->>SERVICE: Automation rules
        SERVICE->>DB: Query deals matching triggers
        DB-->>SERVICE: Matching deals
        SERVICE->>ACTION: Execute workflow actions
        ACTION->>DB: Update deal status
        ACTION->>DB: Create tasks
        ACTION->>ACTION: Send emails/webhooks
    end

Key Features

• Event Triggers: Deal created, updated, stage changed, won, lost
• Condition Matching: Complex condition evaluation
• Multi-Action Workflows: Execute multiple actions in sequence
• Timing Controls: Immediate or delayed execution
• Assignment Rules: Auto-assign based on criteria
• Notification Actions: Email, SMS, Slack notifications
• Webhook Integration: Trigger external systems
• Task Creation: Auto-create follow-up tasks

Automation Triggers

Deal Events:

• Deal created
• Deal updated
• Stage changed
• Deal value changed
• Deal won
• Deal lost
• Activity added
• Note added

Conditions:

• Deal value thresholds
• Time in stage
• Owner changes
• Custom field values
• Tag additions

Automation Actions

Deal Actions:

• Update deal fields
• Change stage
• Assign owner
• Add tags
• Update custom fields

Communication Actions:

• Send email to contact
• Send email to owner
• SMS notification
• Slack message

Task Actions:

• Create follow-up task
• Create reminder
• Schedule call

Integration Actions:

• Webhook POST request
• Update external CRM
• Trigger Zapier workflow

Execution Rules

Frequency Limits:

• Per-deal: Once per automation
• Per-trigger: Configurable limits
• Cooldown periods: Prevent spam

Priority Handling:

• High-priority deals first
• Time-sensitive actions prioritized
• Queue depth monitoring

---

🔗 Related Documentation

• Queue Manager Overview
• Architecture (documentation unavailable)
• Configuration

---

Module Status: Active
Execution Pattern: High-frequency polling
Last Updated: 2025-10-10