SCPCC-Notion Automation

Automated scripts for syncing Pipedrive CRM data to Notion databases, providing real-time KPI tracking for sales performance.

📊 What This Does

Syncs KPI data from Pipedrive to a Notion database, tracking weekly performance metrics for your sales team:

• New Qualified Opps - Deals that reached qualified status
• Meetings On Calendar - Scheduled meetings for the week
• Meetings Scheduled - New meetings added
• Meetings Conducted - Completed meetings
• Proposal Follow-Up - Proposal follow-up activities completed
• Revenue Closed - Dollar value of deals invoiced

Key Features

✅ Automatic Updates - Runs twice daily (midnight & noon Pacific) ✅ Historical Data - Backfill script for past weeks ✅ Weekly Tracking - Sunday-Saturday weeks to match Pipedrive ✅ Goal Tracking - Pulls goals from separate Goals database ✅ Smart Updates - Updates existing week data, creates new rows on Sundays only

---

🚀 Quick Start

Prerequisites

• Python 3.11+
• Notion account with API access
• Pipedrive account with API access
• GitHub repository (for automated runs)

Local Setup

1. Clone the repository

   git clone https://github.com/yourusername/SCPCC-Notion.git
   cd SCPCC-Notion

2. Install dependencies

   cd scripts/pipedrive
   pip install -r requirements.txt

3. Configure environment

   cp config/example.env .env
   # Edit .env with your actual API tokens

4. Run the sync

   source .env  # Load environment variables
   python sync_kpis.py

---

⚙️ Configuration

Required Environment Variables

Create a .env file in the project root with these values:

# Notion Configuration
NOTION_API_TOKEN=your_notion_api_token_here
KPI_NOTION_DATABASE_ID=your_kpi_database_id_here

# Pipedrive Configuration
PIPEDRIVE_API_TOKEN=your_pipedrive_api_token_here

# Optional Configuration
TIMEZONE=America/Los_Angeles

GitHub Secrets

For automated runs via GitHub Actions, add these secrets to your repository:

1. Go to Settings → Secrets and variables → Actions
2. Add the following secrets:
   • NOTION_API_TOKEN
   • KPI_NOTION_DATABASE_ID
   • PIPEDRIVE_API_TOKEN
   • TIMEZONE (optional, defaults to America/Denver)

---

📁 Project Structure

SCPCC-Notion/
├── .github/workflows/
│   ├── kpi-sync.yml          # Automated sync (runs 2x daily)
│   └── lint.yml              # Code quality checks
├── config/
│   └── example.env           # Example environment variables
├── docs/
│   └── kpi-sync.md          # Detailed documentation
├── scripts/
│   └── pipedrive/
│       ├── sync_kpis.py      # Main sync script (updates/creates rows)
│       ├── backfill_weeks.py # Historical data backfill
│       ├── init_database.py  # Initialize database with rows
│       ├── utils.py          # Shared utilities
│       ├── mappings.py       # Salesperson & activity mappings
│       └── requirements.txt  # Python dependencies
└── README.md

---

🔧 Scripts

sync_kpis.py - Main Sync Script

Purpose: Daily sync that updates current week data or creates new week rows on Sundays.

Usage:

cd scripts/pipedrive
python sync_kpis.py

Behavior:

• Monday-Saturday: Updates existing 18 rows for current week
• Sunday: Creates 18 new rows for the new week
• Fetches fresh data from Pipedrive twice daily

---

backfill_weeks.py - Historical Data Backfill

Purpose: One-time script to populate historical KPI data for all weeks in the current year.

Usage:

cd scripts/pipedrive
python backfill_weeks.py

Output: Creates rows for every week from Jan 1 to present (e.g., 41 weeks × 3 salespeople × 6 KPIs = 738 rows)

---

init_database.py - Database Initialization

Purpose: Creates initial rows in Notion database for testing.

Usage:

cd scripts/pipedrive
python init_database.py

Note: Only needed for initial setup or testing. sync_kpis.py handles ongoing row creation.

---

📊 Notion Database Setup

KPI Database Schema

Your Notion KPI database must have these properties:

Property Name	Type	Description
KPI	Title	KPI name (e.g., "Revenue Closed")
Salesperson	Rich Text	Salesperson name
Week	Date	Sunday date of the week (YYYY-MM-DD)
Current	Number	Current value for the KPI
Goal	Number	Goal value for the KPI
Last Sync	Date	Timestamp of last update

Goals Database Schema

Create a separate Goals database with:

Property Name	Type	Description
Name	Title	Salesperson name
New Qualified Opps	Number	Weekly goal
Meetings On Calendar	Number	Weekly goal
Meetings Scheduled	Number	Weekly goal
Meetings Conducted	Number	Weekly goal
Proposal Follow-Up	Number	Weekly goal
Revenue Closed	Number	Weekly goal (in dollars)

---

🎯 KPI Definitions

1. New Qualified Opps

What it measures: Count of deals that reached "qualified" status during the week.

Data source: Pipedrive custom field "Date Qualified (Later Part of Sales Pipeline)"

Logic: Counts deals where qualified date falls within the week range.

---

2. Meetings On Calendar

What it measures: Number of meetings scheduled to occur during the week.

Data source: Pipedrive activities with types:

• "Meeting - Qualify"
• "Meeting - Discovery"
• "Meeting - Engage/Data Review"
• "Meeting - Learn/Project Review"

Logic: Counts activities where due_date falls within the week.

---

3. Meetings Scheduled

What it measures: Number of new meetings added during the week.

Data source: Same meeting activity types as above.

Logic: Counts activities where add_time (creation date) falls within the week.

---

4. Meetings Conducted

What it measures: Number of meetings completed during the week.

Data source: Same meeting activity types as above.

Logic: Counts activities marked as done where marked_as_done_time falls within the week.

---

5. Proposal Follow-Up

What it measures: Number of proposal follow-up activities completed.

Data source: Pipedrive activities with type "Proposal Follow-up"

Logic: Counts activities marked as done where marked_as_done_time falls within the week.

---

6. Revenue Closed

What it measures: Total dollar value of deals invoiced during the week.

Data source: Pipedrive deals in "Invoiced (Current)" stage (Stage ID: 101)

Logic: Sums deal values where:

• Deal entered "Invoiced (Current)" stage during the week
• Deal status is "open" or "won" (not lost/deleted)

---

🤖 GitHub Actions Automation

Automatic Sync Schedule

The workflow runs automatically:

• 12:00 AM PST (midnight)
• 12:00 PM PST (noon)

Manual Trigger

Run the sync manually:

1. Go to Actions tab in GitHub
2. Select "KPI Sync (Pipedrive → Notion)"
3. Click "Run workflow"

---

🗺️ Salesperson Mappings

Update scripts/pipedrive/mappings.py to map your Notion names to Pipedrive users:

SALESPERSON_TO_PD_USER = {
    "Daniel Rico": "Daniel Rico",
    "Shasta Wickham": "Shasta Wickham",
    "Isaac Lopez": "Isaac Lopez",
}

---

🐛 Troubleshooting

"404 Not Found" Error

• Verify your Notion integration has access to both databases
• Check that database IDs are correct (copy from database URL)

"KeyError: NOTION_API_TOKEN"

• Ensure environment variables are loaded: source .env
• Check that .env file exists and has correct values

Wrong Week Dates

• Weeks run Sunday-Saturday to match Pipedrive
• Week field shows the Sunday date (start of week)

No Data Appearing

• Run init_database.py first to create initial rows
• Check that Pipedrive API token has correct permissions
• Verify salesperson names match exactly in mappings.py

---

🔄 Development Workflow

Making Changes

1. Create a feature branch

   git checkout -b feature/your-feature-name

2. Make your changes

   # Edit files

3. Format code

   black scripts/
   ruff check scripts/

4. Test locally

   cd scripts/pipedrive
   python sync_kpis.py

5. Commit and push

   git add .
   git commit -m "feat(sync): your description"
   git push origin feature/your-feature-name

Code Style

• Python: Black formatter, Ruff linter
• Commits: Conventional commits format
• Branches: feature/, fix/, docs/ prefixes

---

📝 License

MIT License - See LICENSE file for details

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run linting and formatting
5. Submit a pull request

---

📞 Support

For issues or questions:

• Open a GitHub issue
• Check the docs folder for detailed runbooks
• Review the troubleshooting section above

---

Built with ❤️ for sales team performance tracking