Importing Demo Data

Importing Demo Data via Admin Pages

Overview

ChurchCRM includes a demo data import feature that allows you to quickly populate your installation with sample families, people, groups, and other realistic data. This is ideal for:

• Testing and evaluation: Explore ChurchCRM features with realistic data before committing to production use
• Training: Train staff and volunteers on a system that looks like your actual church
• Development: Test custom reports, workflows, and integrations with representative data
• Demonstrations: Show ChurchCRM to decision-makers with a fully populated system

Important Prerequisites

⚠️ CRITICAL: Demo data import is only available on fresh installations with exactly 1 person (the initial admin user). This safety check prevents accidental data overwrites on production systems.

Before Importing Demo Data

1. Fresh Installation Required: The system must have only the default admin user (1 person total)
2. Database Should Be Clean: No existing families, groups, events, or financial data (beyond the initial setup)
3. Backup First: Even on fresh installations, consider creating a backup before importing

When NOT to Import Demo Data

❌ DO NOT import demo data if:

• You have already added real families, people, or groups
• Your system is in production use
• You need to preserve any existing data

Note: There is a force option in the API that bypasses the safety check, but this is only for developers/testing and is not exposed in the UI to prevent accidental data loss.

---

How to Import Demo Data

Step 1: Access the Admin Dashboard

1. Log in to ChurchCRM as an administrator
2. Navigate to the Admin Dashboard:
   • Click on Admin in the main navigation menu
   • The dashboard will load at /admin

Step 2: Locate the Demo Data Card

On the Admin Dashboard, you'll find the Demo Data card in the right sidebar:

The card displays:

• Title: "Demo Data"
• Description: "Import sample families, people, and groups to explore ChurchCRM with realistic data"
• Button: "Import Demo Data" (green button with download icon)

Step 3: Start the Import Process

1. Click the "Import Demo Data" button
2. A full-screen confirmation modal will appear with:
   • Reset Instructions: Important information about database prerequisites
   • Import Options: Checkboxes to customize what data to include
   • Action Buttons: Confirm or cancel the import

Step 4: Configure Import Options

The confirmation modal offers several import options:

Available Options

• 🎉 Include Events & Attendance (Optional)

  • Imports sample calendar events
  • Includes check-in/check-out records
  • Demo event types and attendance tracking
  • Default: Unchecked

• 💰 Include Financial Data (Optional)

  • Imports donation funds
  • Sample pledges and payment records
  • Deposit slips and financial tracking data
  • Default: Unchecked
  • ⚠️ Important: Only enable if you plan to test the Finance module

• 📚 Include Sunday School Classes (Optional)

  • Imports Sunday School groups and class assignments
  • Sample teacher/student relationships
  • Age-appropriate class structures
  • Default: Unchecked

Recommended Configuration

For most evaluation purposes:

• ✅ Leave all options unchecked for basic family/people/groups data only
• ✅ Enable specific options only if you need to test those features

Step 5: Confirm and Import

1. Review the warning message about database reset requirements
2. Select your desired options (or leave unchecked for basic data)
3. Click the "Yes, Import Demo Data" button (green button)
   • To cancel, click "Cancel" (gray button)

Step 6: Wait for Import to Complete

Once confirmed:

1. A full-screen loading spinner will appear with the message:
   • "Importing Sample Data..."
   • "This may take a moment. Please do not close this window."
2. The spinner blocks all user interaction to prevent interruptions
3. Import typically takes 10-30 seconds depending on:
   • Selected options
   • Server performance
   • Database speed

Step 7: Review Import Results

When the import completes:

1. The spinner will disappear

2. A success notification will display showing:

   • ✅ "Demo data loaded successfully"
   • Summary of imported items:
     • Number of families added
     • Number of people added
     • Number of groups created
     • Number of notes imported
   • Elapsed time in seconds

3. If errors occurred:

   • ❌ Error notifications will display
   • Check the system logs at /admin/system/logs for details

---

What Data Gets Imported

The demo data includes realistic church information pulled from JSON files in the codebase. Here's what you can expect:

Core Data (Always Imported)

👨‍👩‍👧‍👦 Families

• Sample families with diverse household structures:
  • Traditional nuclear families
  • Single-parent households
  • Empty nesters
  • Singles and young adults
• Each family includes:
  • Complete address information
  • Phone numbers and emails
  • Family notes and history
  • Optional family photos (for some families)

👤 People

• Individual person records with:
  • Full names (first, middle, last, suffix)
  • Birth dates (age-appropriate for roles)
  • Gender assignments
  • Personal contact information
  • Classification (Member, Regular Attender, Visitor, etc.)
  • Optional profile photos (for some individuals)
• People are properly linked to their families
• Realistic family member relationships

📝 Notes

• Sample notes attached to persons and families:
  • Pastoral care notes
  • Contact history
  • Membership milestones
  • General observations

👥 Groups

• Basic ministry groups and small groups:
  • Adult Bible Study groups
  • Women's Ministry
  • Men's Fellowship
  • Youth Group
  • Worship Team
  • Volunteer groups
• Group memberships with appropriate roles (Leader, Member, etc.)
• Realistic group sizes and participation patterns

Optional Data (Based on Selections)

🎉 Events & Attendance (if enabled)

• Calendar events:
  • Sunday worship services
  • Midweek Bible studies
  • Special events (Easter, Christmas, etc.)
  • Community outreach events
• Attendance records:
  • Check-in/check-out timestamps
  • Event participation tracking
  • Regular attender patterns

💰 Financial Data (if enabled)

• Donation funds:
  • General Fund
  • Building Fund
  • Missions
  • Special offerings
• Pledges:
  • Annual giving commitments
  • Pledge tracking and fulfillment
• Payments and deposits:
  • Sample donation records
  • Deposit slips
  • Payment methods (Check, Cash, Online)

📚 Sunday School Classes (if enabled)

• Age-graded classes:
  • Nursery (0-2 years)
  • Preschool (3-5 years)
  • Elementary (6-11 years)
  • Middle School (12-14 years)
  • High School (15-18 years)
  • Adult classes
• Teacher assignments
• Student enrollments
• Class schedules and rooms

System Configuration

The import also loads demo-specific system settings:

• Church name and information
• Time zones and date formats
• Feature enablement flags
• UI preferences

---

Technical Details

Under the Hood

The demo data import process:

1. Validation: Checks that exactly 1 person exists (safety check)
2. System Config: Imports demo-specific settings from system-config.json
3. People Import: Loads families and people from people.json
   • Creates Family records
   • Creates Person records
   • Links people to families
   • Imports family/person notes
   • Optionally imports photos
4. Groups Import: Loads groups from groups.json
   • Creates Group records
   • Assigns group members
   • Sets member roles (Leader, Member, etc.)
   • Optionally creates Sunday School groups
5. Results: Returns detailed import statistics

Data Location

Demo data files are located in the codebase at:

• JSON files: src/admin/demo/
  • people.json - Families, people, and notes
  • groups.json - Groups and memberships
  • system-config.json - Demo-specific system settings
• Photos: src/admin/demo/photos/ (optional)
  • Family photos
  • Person profile photos

API Endpoint

The import is handled by: POST /admin/api/demo/load

Request Body:

{
  "includeFinancial": false,
  "includeEvents": false,
  "includeSundaySchool": false,
  "force": false
}

Response:

{
  "success": true,
  "message": "Demo data loaded successfully",
  "imported": {
    "groups": 15,
    "families": 50,
    "people": 175,
    "notes": 25
  },
  "warnings": [],
  "errors": [],
  "elapsedSeconds": 12.45
}

Service Layer

The import logic is implemented in:

• Service: ChurchCRM\Service\DemoDataService
• Method: importDemoData(bool $includeFinancial, bool $includeEvents, bool $includeSundaySchool)

---

Troubleshooting

"Demo data import is only available on fresh installations"

Problem: You see this error message when trying to import.

Cause: Your system has more than 1 person (the default admin user).

Solutions:

1. Fresh Installation: If you haven't added real data yet, reset your database:
   • Use the backup/restore feature to restore a fresh database
   • Or reinstall ChurchCRM from scratch
2. Development Override: If you're a developer and need to force import (⚠️ this will overwrite data):
   • Use the API directly with force: true parameter
   • This is NOT recommended for production use

Import Fails or Times Out

Problem: The import process fails or seems to hang.

Causes & Solutions:

1. Server timeout:
   • Increase PHP max_execution_time in php.ini
   • Recommended: 120 seconds or more
2. Memory limit:
   • Increase PHP memory_limit in php.ini
   • Recommended: 256M or more
3. Database connection:
   • Check database credentials in Include/Config.php
   • Verify database server is running
   • Check database server logs

Unknown Errors During Import

Problem: Import fails with generic error message.

Solution: Check the application logs:

1. Navigate to Admin → System → Logs
2. View the Application Log (app.log)
3. Look for entries with timestamp matching the import
4. Common issues logged:
   • JSON parse failures
   • Missing data files
   • Propel ORM errors
   • File permission issues

Demo Data Doesn't Look Right

Problem: Imported data seems incomplete or inconsistent.

Solutions:

1. Check import results: Review the success message for counts
   • Expected: 50+ families, 175+ people, 15+ groups
2. Verify options: Ensure you selected the options you wanted
   • Financial data won't appear if you didn't check the option
3. re-import: If safe to do so:
   • Reset your database
   • Re-run the import with desired options

---

Resetting After Demo Import

If you want to remove demo data and start fresh:

Option 1: Restore from Backup

1. Navigate to Admin → System → Backup & Restore
2. Restore a backup taken before the demo import
3. All demo data will be removed

Option 2: Fresh Installation

1. Drop and recreate your ChurchCRM database
2. Re-run the ChurchCRM installer
3. Configure your fresh system

Option 3: Manual Cleanup (Not Recommended)

Manually deleting demo data is not recommended because:

• You risk deleting real data added after import
• Database relationships make manual cleanup error-prone
• Better to restore from backup or reinstall

---

Best Practices

For Evaluation/Testing

1. ✅ Import early: Load demo data right after installation
2. ✅ Try features: Test reports, emails, and workflows with realistic data
3. ✅ Export samples: Generate sample reports and PDFs to evaluate output quality
4. ✅ Test multi-user: Create additional user accounts to test permissions

For Training

1. ✅ Include all modules: Enable Financial, Events, and Sunday School options
2. ✅ Document workflows: Use demo data to create training materials
3. ✅ Practice scenarios: Have trainees perform common tasks with demo families
4. ✅ Reset between sessions: Restore demo state between training sessions

For Development

1. ✅ Use version control: Track changes to demo data files
2. ✅ Test both ways: Test with and without optional data modules
3. ✅ Validate imports: Check logs for warnings/errors after import
4. ✅ Update demo data: Keep demo data synchronized with schema changes

---

Additional Resources

• System Logs: /admin/system/logs - View detailed import logs
• Backup & Restore: /admin/system/backup - Manage database backups
• User Management: /admin/system/users - Create additional test users
• System Settings: /admin/system/settings - Configure ChurchCRM behavior

---

FAQ

Q: Can I import demo data multiple times?
A: Only on fresh installations with 1 person. If you've already imported demo data, you'll need to reset your database first.

Q: Will demo data overwrite my existing families?
A: The import has a safety check that prevents importing if more than 1 person exists. This protects your data.

Q: Can I customize the demo data?
A: Yes! Developers can edit the JSON files in src/admin/demo/ to customize families, people, groups, and other data. After editing, run the import to load your custom data.

Q: How long does import take?
A: Typically 10-30 seconds, depending on server performance and selected options. Financial and event data take slightly longer.

Q: Can I delete specific demo families after import?
A: Yes, but this removes ALL linked data (people, notes, groups, etc.). It's better to restore from backup and re-import if you need different demo data.

Q: Does demo data include real people's information?
A: No. All demo data uses fictional names, addresses, emails, and phone numbers. It's completely synthetic data created for demonstration purposes.

Q: What happens if import fails partway through?
A: The import uses database transactions where possible, but partial data may remain. Check system logs for errors and consider resetting the database and re-importing.

---

Last Updated: February 16, 2026
ChurchCRM Version: 6.x and later