Skip to main content

Troubleshooting & FAQs

Critical Support Resource

🛠️ System Problem Resolution: Comprehensive diagnostic guide covering SMS configuration, engagement plan assignment, settings validation, permission issues, and performance optimization with step-by-step resolution procedures.

🔧 Systematic Problem Solving: Master the art of diagnosing and resolving Pastoral Care system issues with detailed troubleshooting procedures, common problem patterns, and preventive maintenance strategies.

🎯 Quick Diagnostic​

Emergency Troubleshooting Checklist

✅ Step 1: Identify problem category (SMS, Settings, Permissions, Performance)
✅ Step 2: Check system requirements and configuration prerequisites
✅ Step 3: Validate user permissions and access levels
✅ Step 4: Review recent system changes and updates
✅ Step 5: Apply systematic diagnostic procedures for problem resolution

📋 Table of Contents​

📱 SMS & Mobile Issues​

🚨 Critical SMS Problems​

Mobile Device Requirement

🔴 CRITICAL: SMS functionality ONLY works on actual mobile devices. Desktop browsers and laptop computers cannot send SMS messages through the Pastoral Care system.

Problem: textMerge LWC not sending SMS messages

🔍 SMS Diagnostic Checklist

Mobile Device Verification​

  • ✅ Using Actual Mobile Device - SMS only works on phones/tablets, not desktop
  • ✅ Salesforce Mobile App - Using official Salesforce mobile application
  • ✅ Active Mobile Data - Device has active cellular or WiFi connection
  • ✅ Mobile Browser Alternative - Mobile browser access to Salesforce (if not using app)

Component Placement Verification​

  • ✅ textMerge LWC Present - Component visible on record page
  • ✅ Component Permissions - User has access to SMS component
  • ✅ Page Layout Integration - Component properly added to Lightning page
  • ✅ Mobile Responsive - Component displays correctly on mobile screen

Custom Settings Configuration​

  • ✅ Object API Name Configured - Target object in Pastoral_Care_Custom_Settings__c
  • ✅ Phone Field API Names - Correct phone field mapping
  • ✅ Field Access Permissions - User can access configured phone fields
  • ✅ Custom Settings Access - User has read access to custom settings

Data Validation​

  • ✅ Phone Number Present - Target record has phone number in configured fields
  • ✅ Phone Number Format - Phone number in correct format for SMS delivery
  • ✅ Field Population - Phone fields contain valid data
  • ✅ Merge Field Test - Text template merge fields populating correctly

Resolution Steps:

  1. Verify Mobile Device Usage

    ❌ Desktop Computer → ✅ Switch to Mobile Device
    ❌ Laptop Browser → ✅ Use Phone or Tablet
    ❌ Desktop Salesforce → ✅ Salesforce Mobile App or Mobile Browser

  2. Check Component Integration

    • Navigate to Lightning App Builder
    • Verify textMerge LWC is added to record page
    • Confirm component has proper visibility settings
    • Test component displays on mobile device

  3. Validate Custom Settings

    • Setup → Custom Settings → Pastoral Care Custom Settings
    • Verify Object API Names match target objects
    • Confirm Phone Field API Names are correct
    • Test field access with target user profile

  4. Test Phone Field Configuration

    • Check phone number exists in configured fields
    • Verify field-level security allows user access
    • Confirm phone number format is SMS-compatible
    • Test merge field population in text templates

⚙️ Settings & Configuration Problems​

🎛️ Settings Dashboard Issues​

Problem: System shows multiple active Pastoral Care Settings records

Critical Configuration Error

Having multiple active settings records can cause unpredictable system behavior, email routing failures, and automation conflicts.

🔧 Active Settings Resolution Process

Immediate Resolution Steps​

  1. Identify Active Records

    Pastoral Care App → Pastoral Care Settings Tab
    Filter: Active = True
    Expected Result: Only 1 record should show

  2. Deactivate Duplicates

    • Select excess active records
    • Edit each record
    • Uncheck "Active" field
    • Save records

  3. Validate Single Active Record

    • Confirm only one record remains active
    • Test system functionality
    • Monitor for automation conflicts

Prevention Strategy​

  • Settings Validation Flow - Ensure validation flow is active
  • User Training - Educate administrators on single active rule
  • Change Control - Implement approval process for settings changes
  • Regular Audit - Monthly review of active settings records

Troubleshooting Settings Conflicts​

  • Email Template Routing - Check if emails route to correct templates
  • Campaign Integration - Verify campaign associations work correctly
  • Phone Field Configuration - Confirm SMS field mappings function
  • Team Notifications - Test team-specific alert routing

Quick Fix:

  1. Navigate → Pastoral Care Settings → List View
  2. Filter → Active = True
  3. Select Extra Records → Edit → Uncheck Active → Save
  4. Verify → Only one active record remains
  5. Test → Confirm system functions correctly

🔗 Engagement Plan Assignment Issues​

🎯 NPSP Integration Problems​

Problem: Engagement plans not automatically assigned to caring cases

Name Matching Logic

The system uses exact name matching between Caring Case record types and Engagement Plan Template names to automatically assign appropriate plans.

🔍 Assignment Rule Diagnostic Process

Name Matching Verification​

  1. Record Type Names

    Setup → Object Manager → Caring Case → Record Types
    Example Names:
    - Bereavement
    - Academic Support
    - Patient Advocacy
    - Employee Assistance

  2. Engagement Plan Template Names

    NPSP → Engagement Plans → Engagement Plan Templates
    Required Matching Names:
    - Bereavement Engagement Plan Template (matches "Bereavement" record type)
    - Academic Support Engagement Plan Template
    - Patient Advocacy Engagement Plan Template
    - Employee Assistance Engagement Plan Template

Flow Logic Validation​

  1. Assignment Flow Status

    • Setup → Flows → Search "Engagement Plan Assignment"
    • Verify flow is active and has no errors
    • Check flow logic for name matching algorithm
    • Review flow interview logs for errors

  2. Flow Testing Process

    • Create caring case with specific record type
    • Monitor flow execution in debug mode
    • Verify name matching logic performs correctly
    • Check for flow errors or execution failures

Common Assignment Issues​

  • Name Mismatch - Engagement plan template name doesn't exactly match record type
  • Template Inactive - Engagement plan template is not active
  • Flow Errors - Assignment flow has logic errors or permissions issues
  • Case Owner Issues - Flow cannot assign engagement plan to case owner

Quick Resolution:

  1. Verify Exact Name Matching

    Record Type: "Bereavement"
    Required Template: "Bereavement Engagement Plan Template"

    ❌ "Bereavement Support Template" (doesn't match)
    ✅ "Bereavement Engagement Plan Template" (exact match)

  2. Test Assignment Process

    • Create test caring case with specific record type
    • Verify engagement plan automatically assigned
    • Check assignment ownership and permissions
    • Monitor for flow errors or execution issues

🔐 Permission & Access Problems​

👥 User Access Configuration​

Problem: Users cannot access Pastoral Care features or components

🔐 Permission Configuration Guide

Required Permission Sets​

  1. Pastoral Care Admin - Full administrative access

    Object Permissions:
    - Caring_Case__c: Read, Create, Edit, Delete
    - Text_Template__c: Read, Create, Edit, Delete
    - Pastoral_Care_Setting__c: Read, Create, Edit, Delete
    - Custom Settings: Read, Modify All

  2. Pastoral Care User - Standard user access

    Object Permissions:
    - Caring_Case__c: Read, Create, Edit (own records)
    - Text_Template__c: Read, Create, Edit (own templates)
    - Contact: Read, Edit (for SMS integration)
    - Campaign: Read, Edit Members

  3. Mobile SMS User - Mobile device SMS access

    Component Access:
    - textMerge LWC: Visible and accessible
    - Pastoral Care mobile app: Access enabled
    - Custom Settings: Read access for SMS configuration
    - Phone fields: Read access on all relevant objects

Permission Troubleshooting Process​

  1. User Assignment Verification

    • Setup → Users → Select User → Permission Set Assignments
    • Verify required permission sets are assigned
    • Check assignment dates and expiration
    • Confirm permission set activation status

  2. Object-Level Permission Check

    • Permission Sets → Select Permission Set → Object Settings
    • Verify CRUD permissions for Pastoral Care objects
    • Check field-level security for critical fields
    • Confirm custom settings access permissions

  3. Component Access Validation

    • Lightning Components → textMerge → Permissions
    • App Access → Pastoral Care App → User inclusion
    • Tab Visibility → Pastoral Care tabs → User access
    • Mobile Settings → Component visibility → User configuration

Quick Permission Fix:

  1. Admin Permission Set Assignment
    • Setup → Users → Select User → Permission Set Assignments
    • Assign "Pastoral Care Admin" or "Pastoral Care User"
    • Verify assignment takes effect immediately
    • Test user access to key features

📧 Email & Communication Issues​

📨 Email Delivery Problems​

Problem: Automated emails from caring cases not delivering to team members

📧 Email Delivery Troubleshooting

Email Template Validation​

  1. Template Configuration Check

    Setup → Email Templates → Locate template from settings
    Validation Checklist:
    - Template is active and approved
    - Merge fields are valid and populated
    - Email body renders correctly
    - Subject line is clear and informative

  2. Template Testing Process

    • Send test email using template
    • Verify merge fields populate correctly
    • Check email formatting and appearance
    • Confirm email reaches test recipients

Email Deliverability Issues​

  1. Salesforce Email Limits

    • Check organization email limits
    • Review daily email send quotas
    • Monitor email deliverability metrics
    • Verify sender reputation status

  2. Recipient Email Configuration

    User/Contact Email Settings:
    - Valid email addresses in user/contact records
    - Email opt-out settings not blocking emails
    - Spam filter configuration
    - Email client compatibility

Workflow and Automation Check​

  1. Email Alert Automation

    • Process Builder or Flow triggering email alerts
    • Workflow rules executing correctly
    • Email alert criteria and conditions
    • Timing and execution sequence

  2. Settings Integration

    • Active settings record configuration
    • Email template assignment correctness
    • Team-specific routing functionality
    • Confidentiality level email routing

Quick Email Fix:

  1. Template Verification - Confirm template exists and is active
  2. Recipient Check - Verify email addresses are valid and current
  3. Automation Test - Create test case and monitor email generation
  4. Delivery Monitoring - Check email logs for delivery confirmation

🎨 Template & Customization Problems​

🔧 Lightning Page Issues​

Problem: Lightning pages not displaying correctly or missing components

⚡ Lightning Page Troubleshooting

Component Display Issues​

  1. Component Visibility Settings

    Lightning App Builder → Select Page → Edit
    Component Settings:
    - Visibility rules and criteria
    - Device-specific display settings (mobile/desktop)
    - User permission requirements
    - Record type or field-based visibility

  2. Component Configuration Validation

    • Component properties correctly configured
    • Required fields and parameters set
    • Component size and layout appropriate
    • Component interactions functioning correctly

Page Activation and Assignment​

  1. Page Activation Status

    Lightning App Builder → Page Settings:
    - Page activation status (active/inactive)
    - App and record type assignments
    - User profile and permission set assignments
    - Default page assignments and overrides

  2. Assignment Troubleshooting

    • Verify page assigned to correct app
    • Check record type and profile assignments
    • Confirm user access to page and components
    • Validate page load and rendering performance

Common Flexipage Issues​

  • Component Permissions - Users lack access to page components
  • App Assignment - Page not assigned to user's active app
  • Record Type Conflicts - Page assignment conflicts with record types
  • Mobile Compatibility - Page not optimized for mobile devices

⚡ Performance & System Issues​

🚀 System Performance Problems​

Problem: Pastoral Care system running slowly or timing out

🚀 Performance Optimization Guide

Performance Diagnostic Process​

  1. System Load Analysis

    Performance Monitoring:
    - Page load times across different components
    - Component rendering speed on mobile devices
    - Database query performance and optimization
    - Network connectivity and data transfer speeds

  2. User Activity Monitoring

    • Concurrent user load and system impact
    • Peak usage time identification
    • Feature utilization patterns
    • Mobile vs desktop performance differences

Optimization Strategies​

  1. Lightning Page Optimization

    Page Performance Improvements:
    - Reduce number of components per page
    - Optimize component size and complexity
    - Implement lazy loading for non-critical components
    - Use caching for frequently accessed data

  2. Data and Query Optimization

    • Limit related list record counts
    • Optimize SOQL queries in custom components
    • Implement appropriate indexes on custom fields
    • Use selective queries and field sets

Mobile Performance Enhancement​

  1. Mobile-Specific Optimization

    • Component size optimization for mobile screens
    • Touch interface optimization
    • Reduce data transfer for mobile connections
    • Implement offline capabilities where appropriate

  2. Component Performance

    • textMerge LWC optimization for mobile use
    • Reduce JavaScript execution complexity
    • Optimize component state management
    • Implement efficient error handling

📞 Support Resources​

🆘 Getting Additional Help​

Complete Documentation Library:

📖 Comprehensive Documentation Guide

Core Functionality Documentation​

Communication and Integration​

Advanced Administration​

Analytics and Reporting​

Self-Service Resources​

  • Video Tutorials - Step-by-step visual guides for common tasks
  • Best Practices - Organizational implementation guidance
  • FAQ Database - Searchable answers to common questions
  • Community Forum - User community support and knowledge sharing
Effective Troubleshooting

🛠️ Remember: Systematic troubleshooting is the key to resolving issues efficiently. Start with the most common causes (permissions, configuration, mobile device requirements) before moving to complex diagnostics. Document solutions and share them with your team to build organizational knowledge and prevent recurring issues.

📖 Related Documentation: