README.md

---
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](https://huggingface.co/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:
  ```bash
  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](https://www.notion.so/my-integrations)
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:

```bash
# 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