Hugging Face's logo

Spaces:
Wilson826
/
DBExportTool
Running

App Files Community
DBExportTool / README.md
joycecast's picture
joycecast
Update README.md
612ad1b verified
preview code
|
Raw
History Blame Contribute Delete
10.5 kB

A newer version of the Gradio SDK is available: 6.20.0

Upgrade
metadata 
title: Notion DB Export Tool
sdk: gradio
emoji: 💻
colorFrom: yellow
colorTo: green
sdk_version: 5.49.1

Notion Excel Exporter - Hugging Face Spaces

A secure web application for exporting Notion databases to Excel format with three specialized export modes.

Features

  • 3 Export Modes with Separate Tabs:
    • Notion Databases: Export raw Notion database tables with all properties
    • Entry Milestones: Export entry milestone tracking data with CBP/CPSC status
    • MAWB Milestones: Export aggregated SHEIN T01 MAWB milestone data
  • Date Filtering: Filter records by created_time (when records were created in Notion)
  • MAWB Number Input: Specify specific MAWBs to export (comma or newline separated)
  • Rate Limiting Protection: Slow mode and configurable page sizes to prevent API throttling
  • Secure Authentication: Username/password login required
  • Multi-Sheet Excel: Exports multiple databases into a single Excel file with separate sheets
  • Real-time Progress: Shows export status and processing information
  • Export-Only: Does not modify any Notion records (no task auto-checking)

Supported Databases

  • MAWB (Master Air Waybill)
  • Entry Records
  • MAWB Tasks
  • MAWB Milestones (Warehouse milestone records)
  • Dwell Report

Deployment to Hugging Face Spaces

Step 1: Create a New Space

  1. Go to Hugging Face Spaces
  2. Click "Create new Space"
  3. Configure:
    • Space name: notion-excel-exporter (or your preferred name)
    • SDK: Select Gradio
    • Hardware: CPU Basic (free tier is sufficient)
    • Visibility: Private (recommended for security)

Step 2: Upload Files

Upload the following files to your Space:

app.py
notion_exporter.py
entry_milestone_exporter.py
mawb_milestone_exporter.py
requirements.txt
README.md
src/
  └── notion_integration.py

You can either:

  • Use the web interface to drag and drop files
  • Clone the Space repository and push via git:
    git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME
# Copy all files from huggingface-notion-export/ folder
git add .
git commit -m "Initial deployment"
git push

Step 3: Configure Environment Secrets

Go to your Space Settings > Variables and secrets > Add a secret.

Add the following secrets (click "New secret" for each):

Required Notion Configuration:

  • NOTION_API_KEY - Your Notion integration API key
  • MAWB_DB_ID - MAWB database ID (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
  • ENTRY_RECORD_DB_ID - Entry Record database ID
  • MAWB_TASK_DB_ID - MAWB Task database ID
  • MAWB_MILESTONE_DB_ID - MAWB Milestone database ID
  • DWELL_REPORT_DB_ID - Dwell Report database ID (optional)

Authentication Credentials:

  • HF_USERNAME - Login username for the app
  • HF_PASSWORD - Login password for the app

Important Notes:

  • Database IDs should include dashes (format: 247f8938-365a-80d4-bdd1-d9de191b7c05)
  • All secrets are stored securely and never exposed in logs
  • You can skip optional database IDs if not needed

Step 4: Verify Deployment

  1. Wait for the Space to build (usually 2-5 minutes)
  2. Once running, click the app URL
  3. Enter your credentials (HF_USERNAME and HF_PASSWORD)
  4. Test export with a single database first

Getting Notion API Credentials

Notion API Key

  1. Go to Notion Developers
  2. Click "New integration"
  3. Name it (e.g., "Excel Exporter")
  4. Select the workspace
  5. Copy the "Internal Integration Token" (starts with secret_)

Database IDs

  1. Open your Notion database in browser
  2. Copy the URL, which looks like:
    https://www.notion.so/workspace/xxxxxxxxxx?v=yyyyyyyy
  3. The database ID is the part after the last slash and before the ?
  4. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (with dashes)

Grant Access to Databases

For each database:

  1. Open the database in Notion
  2. Click the ... menu in the top right
  3. Select "Add connections"
  4. Find and select your integration
  5. Click "Confirm"

Usage Instructions

Tab 1: Notion Databases

Export raw Notion database tables with all properties automatically captured.

  1. Select Databases: Check one or more databases (MAWB, Entry Records, Tasks, Milestones, Dwell Report)
  2. Set Date Filter (Optional):
    • Filters by created_time (when the record was created in Notion)
    • Enter start date in YYYY-MM-DD format (e.g., 2024-01-01)
    • Enter end date in YYYY-MM-DD format (e.g., 2024-12-31)
  3. Configure Options:
    • Enable "Slow Mode" for large exports or if you encounter rate limits
    • Adjust "Page Size" (lower = safer, higher = faster)
  4. Click Export: Wait for processing to complete
  5. Download: Click the file link to download your Excel file

Tab 2: Entry Milestones

Export entry milestone tracking data with CBP and CPSC status information.

  1. MAWB Numbers (Optional):
    • Leave empty to export all entry records
    • Or enter specific MAWBs (one per line or comma-separated)
    • Example: 369-95208794, 370-12345678
  2. Set Date Filter (Optional):
    • Filters by entry record created_time
    • Enter start/end dates in YYYY-MM-DD format
  3. Click Export: Wait for processing to complete
  4. Download: Excel file includes Entry, MAWB, POD, CBP Line, CPSC Line, release dates, etc.

Tab 3: MAWB Milestones (SHEIN T01)

Export aggregated milestone data for SHEIN T01 MAWBs (one row per MAWB).

  1. MAWB Numbers (Optional):
    • Leave empty to export all SHEIN T01 MAWBs
    • Or enter specific MAWBs (one per line or comma-separated)
  2. Set Date Filter (Optional):
    • Filters by MAWB record created_time
    • Enter start/end dates in YYYY-MM-DD format
  3. Click Export: Wait for processing to complete
  4. Download: Excel file includes aggregated data across all related entries and warehouse milestone records per MAWB

Export Output

Tab 1: Notion Databases Export

  • Single Database: notion_{database_name}_{timestamp}.xlsx
    • Single sheet with database name
  • Multiple Databases: notion_export_{timestamp}.xlsx
    • Multiple sheets: "MAWB Data", "Entry Records", "MAWB Tasks", "MAWB Milestones", "Dwell Report"

Tab 2: Entry Milestones Export

  • All Entries: entry_milestone_export_all_{timestamp}.xlsx
  • Specific MAWBs: entry_milestone_export_specific_{timestamp}.xlsx
  • Sheet: "Entry Milestone Export"
  • Columns: MAWB, Entry, POD, handover_doc, CBP Line, CBP_release, CPSC Line, CPSC_check, CPSC_release, released, etc.

Tab 3: MAWB Milestones Export

  • All SHEIN T01: mawb_milestone_export_all_{timestamp}.xlsx
  • Specific MAWBs: mawb_milestone_export_specific_{timestamp}.xlsx
  • Sheet: "SHEIN_T01_MAWB_Milestones"
  • Columns: MAWB, T01 Entry Submission, PDA scan, T01 CBP Exam, T01 CBP Release, T01 CPSC/PGA Review, T01 CPSC/PGA release, Customs Release, Cargo ready for pickup, Ship out completed, XC shipment list PCS, MAWB POD

Troubleshooting

Rate Limiting Errors

Symptom: Export fails with "429 Too Many Requests" or rate limit errors

Solutions:

  1. Enable "Slow Mode" checkbox
  2. Reduce page size to 25-35
  3. Export fewer databases at once
  4. Wait a few minutes before retrying

Authentication Failed

Symptom: Cannot login to the app

Solutions:

  1. Verify HF_USERNAME and HF_PASSWORD are set correctly in Space secrets
  2. Check for typos in credentials
  3. Restart the Space (Settings > Factory reboot)

Missing Database

Symptom: Error message about missing database ID

Solutions:

  1. Verify the database ID is set in Space secrets
  2. Check the database ID format (must include dashes)
  3. Ensure the integration has access to the database in Notion

Empty Export

Symptom: Excel file is generated but has no data

Solutions:

  1. Check date filters (may be filtering out all records)
  2. Verify the database actually has records in Notion
  3. Ensure the integration has proper permissions

API Rate Limits

Notion API has rate limits:

  • 3 requests per second per integration
  • Burst protection: Can queue up to 10 requests

The exporter handles rate limits with:

  • Automatic delays between requests (0.5-1.5s normal, 2-4s slow mode)
  • Exponential backoff on 429 errors (60s, 120s, 240s, 480s)
  • Configurable page sizes to reduce total API calls

Security Best Practices

  1. Keep Space Private: Set visibility to "Private" in Space settings
  2. Strong Password: Use a complex password for HF_PASSWORD
  3. Rotate Credentials: Periodically update Notion API key and app password
  4. Monitor Access: Check Space logs for suspicious activity
  5. Least Privilege: Only grant integration access to required databases

Project Structure 

huggingface-notion-export/
├── app.py                       # Gradio web interface with 3 tabs
├── notion_exporter.py           # Notion database export logic
├── entry_milestone_exporter.py  # Entry milestone export logic
├── mawb_milestone_exporter.py   # MAWB milestone export logic (SHEIN T01)
├── src/
│   └── notion_integration.py    # Notion API integration
├── requirements.txt             # Python dependencies
├── README.md                    # This file
└── .gitignore                   # Git ignore rules

Local Development

To test locally before deploying:

# Clone the repository
git clone <repo-url>
cd huggingface-notion-export

# Install dependencies
pip install -r requirements.txt

# Set environment variables (create .env file)
export NOTION_API_KEY=your_key
export MAWB_DB_ID=your_db_id
export ENTRY_RECORD_DB_ID=your_db_id
export MAWB_TASK_DB_ID=your_db_id
export MAWB_MILESTONE_DB_ID=your_db_id
export HF_USERNAME=admin
export HF_PASSWORD=password

# Run the app
python app.py

Visit http://127.0.0.1:7860 in your browser.

Support

For issues or questions:

  • Check the troubleshooting section above
  • Review Hugging Face Spaces documentation
  • Verify Notion API integration settings

License

This project is for internal use only.

Version

  • Version: 2.0.0
  • Last Updated: 2025-10-22
  • Notion API Version: 2025-09-03
  • New in v2.0: Added Entry Milestone and MAWB Milestone export modes with MAWB input filtering