Visit Management

A comprehensive Frappe app for managing customer visits and interactions within your CRM system. This app provides a complete solution for tracking, scheduling, and analyzing customer visits, helping sales teams and customer success managers maintain detailed records of all customer interactions.

Features

• Visit Tracking: Complete lifecycle management of customer visits from planning to completion
• CRM Integration: Seamless integration with Frappe CRM for contacts, leads, and organizations
• Status Management: Track visit progress with customizable status workflows
• Rich Documentation: Capture detailed notes, outcomes, and follow-up actions
• Duration Tracking: Monitor visit duration for performance analysis
• User Permissions: Role-based access control for different user types
• API Support: RESTful API endpoints for external integrations
• Comprehensive Logging: Detailed audit trails and error handling

Prerequisites

Required Software

• Frappe Framework: Version 15.0.0 or higher
• Frappe CRM: Must be installed and configured
• Python: Version 3.10 or higher
• Node.js: Version 18.0.0 or higher (for frontend assets)
• Redis: For caching and background jobs
• MariaDB/MySQL: Version 8.0 or higher

System Requirements

• Operating System: Linux (Ubuntu 20.04+, CentOS 8+, or similar)
• RAM: Minimum 4GB, recommended 8GB
• Storage: Minimum 20GB free space
• Network: Outbound internet access for package installation

Installation

⚠️ Important: For production installations, please see PRODUCTION_INSTALL.md for detailed instructions and troubleshooting.

Quick Install

1. Get the app:

   cd ~/frappe-bench
   bench get-app https://github.com/promise4all/visit_management.git

2. Install on your site:

   bench --site your-site install-app visit_management

3. Build assets (REQUIRED):

   bench build

4. Restart services:

   bench restart

If You Encounter Issues

Run the post-install fix script:

cd ~/frappe-bench
./apps/visit_management/post_install_fix.sh

See PRODUCTION_INSTALL.md for comprehensive troubleshooting.

4. Build frontend assets:

   bench build

5. Restart the bench:

   bench restart

Method 2: Manual Installation

1. Clone the repository:

   cd apps
   git clone https://github.com/your-org/visit_management.git
   cd visit_management

2. Install Python dependencies:

   pip install -e .

3. Install Node.js dependencies:

   npm install

4. Build assets:

   npm run build

5. Install the app in your site:

   bench --site [your-site-name] install-app visit_management

Configuration

Basic Configuration

After installation, configure the app through the Frappe Desk interface:

1. Navigate to Settings: Go to "Visit Management" in the module list
2. Configure Permissions: Set up user roles and permissions
3. Customize Fields: Modify visit fields as needed for your business process

Environment Variables

Add these variables to your site_config.json or environment:

{
  "visit_management": {
    "auto_sync_crm": true,
    "default_visit_duration": 60,
    "enable_notifications": true,
    "log_level": "INFO"
  }
}

CRM Integration Setup

1. Verify CRM Installation: Ensure Frappe CRM is properly installed and configured
2. Configure Custom Fields: The app automatically adds necessary fields to CRM entities
3. Set Up Webhooks (Optional): Configure webhooks for real-time synchronization

Usage

Creating a Visit

1. Access Visit Management: Navigate to "Visit Management" > "Visit"

2. Create New Visit: Click "New" button

3. Fill Basic Information:

   • Title: Brief description of the visit
   • Description: Detailed purpose
   • Visit Date: Schedule date and time
   • Status: Set initial status (Planned, In Progress, etc.)

4. CRM Integration:

   • Contact: Link to existing contact or create new
   • Lead: Associate with lead if applicable
   • Organization: Link to organization

5. Visit Details:

   • Purpose: Specific objectives
   • Duration: Expected duration in minutes
   • Notes: Additional context

Managing Visits

Status Workflow

• Planned: Initial status for scheduled visits
• In Progress: Active visit in progress
• Completed: Successfully completed visits
• Cancelled: Cancelled visits with reason

Updating Visit Information

• Modify visit details anytime before completion
• Add notes and outcomes after visit completion
• Track duration and follow-up actions

Reports and Analytics

Access built-in reports:

• Visit Summary by Status
• Visit Duration Analysis
• Contact/Lead Visit History
• Organization Visit Trends

API Documentation

Authentication

All API endpoints require authentication. Use Frappe's built-in API key authentication:

curl -H "Authorization: token [api-key]:[api-secret]" \
     https://your-site.com/api/resource/Visit

Core Endpoints

List Visits

GET /api/resource/Visit

Parameters:

• fields: Comma-separated list of fields to return
• filters: JSON filters (e.g., {"status": "Completed"})
• limit_start: Starting offset for pagination
• limit_page_length: Number of records per page

Create Visit

POST /api/resource/Visit
Content-Type: application/json

{
  "title": "Customer Meeting",
  "description": "Quarterly business review",
  "visit_date": "2024-01-15 10:00:00",
  "status": "Planned",
  "contact": "John Doe",
  "organization": "Acme Corp"
}

Update Visit

PUT /api/resource/Visit/[visit-name]
Content-Type: application/json

{
  "status": "Completed",
  "outcome": "Successful",
  "notes": "Great meeting, follow up scheduled"
}

Delete Visit

DELETE /api/resource/Visit/[visit-name]

Custom API Methods

Get Visit Statistics

GET /api/method/visit_management.api.get_visit_statistics

Parameters:

• from_date: Start date (YYYY-MM-DD)
• to_date: End date (YYYY-MM-DD)
• organization: Filter by organization (optional)

Bulk Update Visits

POST /api/method/visit_management.api.bulk_update_visits
Content-Type: application/json

{
  "visits": ["VISIT-001", "VISIT-002"],
  "updates": {
    "status": "Cancelled"
  }
}

Troubleshooting

Common Issues

Installation Problems

Issue: bench install-app fails with dependency errors Solution:

1. Ensure Frappe CRM is installed first
2. Check Python version compatibility
3. Clear bench cache: bench clear-cache
4. Reinstall with verbose output: bench install-app visit_management --verbose

Issue: Frontend assets not loading Solution:

1. Run bench build to rebuild assets
2. Clear browser cache
3. Check file permissions in sites/assets/

Runtime Issues

Issue: CRM integration not working Solution:

1. Verify CRM app is active in apps.json
2. Check custom fields are properly installed
3. Review logs: bench mariadb then USE [site-name]; SHOW TABLES;
4. Restart bench services

Issue: Permission errors when creating visits Solution:

1. Check user roles in User doctype
2. Verify Visit permissions are set correctly
3. Ensure user has "Visit" doctype permissions

Performance Issues

Issue: Slow visit loading times Solution:

1. Optimize database indexes
2. Enable Redis caching
3. Check for large attachment files
4. Monitor background job queue

Debug Mode

Enable debug logging for troubleshooting:

# In hooks.py or site_config.json
"developer_mode": 1,
"logging": 1

Log Files

Check these log locations:

• Frappe Logs: sites/[site-name]/logs/
• Bench Logs: logs/bench.log
• Nginx Logs: /var/log/nginx/

Getting Help

1. Check Documentation: Review this README and docs/ folder
2. Frappe Community: Post questions on Frappe Forum
3. GitHub Issues: Report bugs and feature requests
4. Professional Support: Contact maintainers for commercial support

Development

Setup Development Environment

1. Install pre-commit hooks:

   cd apps/visit_management
   pre-commit install

2. Run tests:

   bench run-tests visit_management

3. Code formatting:

   pre-commit run --all-files

Project Structure

visit_management/
├── visit_management/           # Main app directory
│   ├── doctype/               # DocType definitions
│   │   └── visit/             # Visit doctype
│   ├── api.py                 # API methods
│   ├── utils.py               # Utility functions
│   ├── crm_integration.py     # CRM integration logic
│   └── hooks.py               # App hooks
├── docs/                      # Documentation
├── tests/                     # Test files
└── README.md                  # This file

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

Testing

The app includes comprehensive tests:

• Unit Tests: Individual function testing
• Integration Tests: Module interaction testing
• API Tests: Endpoint testing
• Performance Tests: Load and timing tests

Run all tests:

bench run-tests visit_management --coverage

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

Version 1.0.0

• Initial release
• Basic visit management functionality
• CRM integration
• API endpoints
• Comprehensive documentation

---

For more information, visit the project repository or contact the development team.