Technical Reference
Task and Activity Architecture
Technical reference for the expanded Task/Activity model, validation, lead rollups, reports, permissions, and best practices
Salesforce stores custom Task fields under the shared Activity metadata object. In this repo, Activity fields extend Task/Event, while Task-specific validation rules, list views, reports, quick actions, triggers, and permissions make Lead activity a first-class data model.
Source Map
| Surface | Source path |
|---|---|
| Custom Activity fields | features-crm/main/default/objects/Activity/fields/* |
| Task list views | features-crm/main/default/objects/Task/listViews/* |
| Task validation rules | features-crm/main/default/objects/Task/validationRules/* |
| Task trigger | features-crm/main/default/triggers/TaskTrigger.trigger |
| Lead conversion trigger | features-crm/main/default/triggers/LeadTrigger.trigger |
| Lead activity service | features-crm/main/default/classes/lead_activity/LeadActivityQualityService.cls |
| Quick actions | features-crm/main/default/quickActions/NewTask.quickAction-meta.xml, LogACall.quickAction-meta.xml, Follow_Up.quickAction-meta.xml |
| Reports | features-crm/main/default/reports/CRM_Performance_Reports/* |
| Dashboard | features-crm/main/default/dashboards/CRM_Performance_Dashboards/LeadPerformanceExecutive.dashboard-meta.xml |
Data Flow
Custom Activity Fields
| Field | Type | Technical purpose |
|---|---|---|
Task_Type__c | Picklist | Canonical task category for reporting and validation. Values include Call, Follow-up, Email, Research, Quote Review, Transfer Handoff, Other. |
Call_Type__c | Picklist | Call subcategory: Prospecting, Discovery, Follow-up, Quote Review, Re-engagement, Transfer Handoff, Other. |
Call_Disposition__c | Picklist | Call outcome. Connected, Qualified, Follow-up Needed, and Converted require deeper buyer intelligence. |
Lead_Activity_Quality_Status__c | Picklist | System-maintained quality status used by reports and Lead rollups. |
Contact_Role__c | Picklist | Role of the person reached: Decision Maker, Influencer, Gatekeeper, Procurement, Owner, Unknown, Other. |
Lead_Interest_Level__c | Picklist | Rep-assessed interest level: High, Medium, Low, Not Interested, Unknown. |
Call_Summary__c | Text Area | Narrative summary required for completed Lead calls. |
Next_Step__c | Text Area | Concrete next action. Required for useful handoff and follow-up reporting. |
Product_Group__c | Lookup to Item_Group__c | Product family discussed. Required by lead activity quality rules. |
Discussed_Item__c | Lookup to Item__c | Optional exact catalog item discussed. |
Product_Interest__c | Text | Product/category/service interest captured from the buyer. |
Buyer_Business_Type__c | Picklist | Business model or buyer type. |
Buying_Stage__c | Picklist | Rep-assessed stage: New Inquiry, Education, Sampling, Pricing, Compliance Review, Ready to Order, Reorder, At Risk, Not a Fit, Unknown. |
Decision_Timeframe__c | Picklist | Expected timing: Today, This Week, This Month, 30-60 Days, 60+ Days, No Timeline, Unknown. |
Primary_Buying_Signal__c | Picklist | Concrete buying signal such as pricing, quote, samples, availability, shipping, payment terms, competitor comparison, ready to order, reorder interest. |
Decision_Criteria__c | Picklist | Driver such as price, margin, product quality, compliance, availability, shipping speed, payment terms, brand recognition, assortment. |
Use_Case__c | Picklist | Retail resale, wholesale distribution, store launch, replenishment, private label, ecommerce, promotion/event, sampling/trial, new category test. |
License_Status__c | Picklist | Restricted-product/compliance state. Non-clean statuses need Compliance Notes. |
Compliance_Notes__c | Text Area | Required context when license status needs review or follow-up. |
Pain_Need__c | Text Area | Business pain, need, or buying driver. |
Objection__c | Text Area | Objection or hesitation. |
Current_Supplier__c | Text | Current supplier or competitor context. |
Competitor__c | Text | Competitor or alternate brand mentioned. |
Risk_Red_Flags__c | Text Area | Risk, credibility, or compliance flags. |
Follow_Up_Required__c | Checkbox | Indicates the activity requires a future follow-up. |
Follow_Up_Due_Date__c | Date | Required when follow-up is required. |
Estimated_Monthly_Order_Value__c | Currency | Buyer-level estimated monthly value. |
Sample_Requested__c | Checkbox | Prospect requested samples or a trial. |
Quote_Requested__c | Checkbox | Prospect requested pricing or quote. |
Lead Rollup Fields
LeadActivityQualityService.refreshLeadSummaries writes these Lead fields from Task state:
| Lead field | Source logic |
|---|---|
Last_Sales_Touch_Date__c | Latest completed structured sales touch by CompletedDateTime, ActivityDate, or CreatedDate. |
Last_Sales_Touch_By__c | Owner of that latest completed sales touch. |
Last_Sales_Touch_Disposition__c | Call disposition or Task status from that latest touch. |
Last_Sales_Touch_Quality__c | Task quality status from that latest touch. |
Next_Follow_Up_Date__c | Earliest open follow-up Task date. |
Open_Follow_Up_Task_Count__c | Count of open follow-up Tasks tied to the Lead. |
Lead_Activity_Compliance_Status__c | Calculated summary: Converted, No Sales Touch, Incomplete Last Touch, No Open Follow-up, Follow-up Overdue, or Current. |
Enforcement Model
| Permission | Assigned to | Behavior |
|---|---|---|
Enforce_Lead_Activity_Quality | Sales performance user/manager paths | Enables structured Lead Task validation. |
Bypass_Lead_Activity_Quality | Sales performance admin/admin cleanup paths | Allows administrative cleanup, imports, and repairs without blocking on rep-entry validation. |
Validation is scoped to Tasks whose WhoId points to a Lead. Non-Lead Tasks should not be blocked by Lead activity quality rules.
Validation Rules
| Rule | Purpose |
|---|---|
Lead_Call_Core_Details_Required | Completed Lead calls require core structured call details and meaningful narrative. |
Lead_Call_Buyer_Intelligence_Required | Connected/qualified/follow-up/converted calls require deeper buyer intelligence. |
Lead_Call_Follow_Up_Due_Date_Required | Follow-up-required calls need a current or future follow-up due date. |
Lead_Call_Compliance_Notes_Required | License statuses that need review require meaningful compliance notes. |
Lead_Task_Open_Core_Details_Required | Open Lead Tasks need task type, due date, product group, and next step. |
Lead_Task_Completed_Core_Required | Completed non-call Lead Tasks need task type, product group, and next step. |
Conversion Gate
Lead conversion calls LeadActivityQualityService.validateLeadConversion. For enforced users, conversion requires a complete structured sales touch in the last 14 days.
The latest structured touch must have quality Complete or Follow-up Scheduled. This prevents converting stale or low-quality lead records into Account/Contact/Opportunity pipeline.
Reporting Surfaces
| Report/list view | Purpose |
|---|---|
Completed_Lead_Calls | Completed calls and captured intelligence. |
Incomplete_Lead_Call_Tasks | Completed call Tasks where quality status is not complete/scheduled. |
Lead_Call_Quality_Review | Manager review for call quality and missing fields. |
Lead_Calls_Missing_Follow_Up | Calls marked follow-up missing. |
Lead_Product_Interest_Calls | Product and buyer-interest review. |
My_Lead_Work_Today | Rep work queue for due follow-ups. |
Lead Tasks Created by Rep | Task volume by creator and status. |
Lead Open Follow-up Tasks by Rep | Open follow-up ownership. |
Leads Without Future Follow-up | Open leads with no structured follow-up. |
Lead Calls Missing Intelligence | Incomplete completed calls. |
Implementation Best Practices
- Add new sales activity data as
Activityfields when the data belongs on Task/Event. - Use validation rules for simple save-time requirements when Apex budget is tight.
- Keep Apex responsible for derived statuses and rollups that must remain consistent across UI, API, delete, undelete, and bulk updates.
- Keep enforcement behind custom permissions. Sales users get enforcement; admins and integrations get explicit bypass.
- Update quick actions and layout requiredness with any new required field so reps see the requirement before save.
- Never build a second custom Task object for lead activity. Use Task/Activity so native activity timeline, reports, ownership, and mobile behavior still work.
- Keep reports visible to sales managers and operators. Hidden admin-only reports defeat the purpose of activity quality work.
- Do not manually edit Lead rollup fields unless performing controlled data repair. They are system-maintained by Task changes.
- If imports create Lead Tasks, populate required structured fields or run through a controlled bypass user and then backfill quality data.
- Before changing conversion rules, test Lead conversion, task save, task delete, undelete, reports, and permission behavior together.
Last updated on