---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-18
name: User_Manual
status: active
tags:
- client/ford
- domain/security
- tech/docker
- tech/python
- tech/sqlite
- type/sop
type: sop
---

# Ford Asset Pack SFTP Transfer System

## What This Tool Does

The Ford Asset Pack SFTP Transfer System automates the movement of asset pack ZIP files from Box cloud storage to Ford's GECHUB SFTP servers. It ensures that assets are correctly distributed across Production (PROD), Education (EDU), and Quality Assurance (QA) environments.

**Core Capabilities:**
- **Automated Monitoring:** Continuously checks specific Box folders for new asset pack ZIP files.
- **Secure Transfer:** Uploads files to designated SFTP servers using dual-factor authentication (Public Key + Password).
- **Record Keeping:** Archives files in Box after successful transfer and logs all events in a local database for reporting.
- **Alerting:** Sends email notifications via Mailgun for successes, failures, or when errors occur.

## Who Uses It

This tool is primarily used by:
- **System Administrators:** To configure and maintain the automation daemon and server configurations.
- **DevOps Engineers:** To manage environment variables, SFTP credentials, and Box API keys.
- **Ford Asset Managers:** To verify transfer reports and ensure assets are correctly deployed to GECHUB environments.

## How to Access

The system runs as a background service (daemon) on the host machine.

1. **Daemon Service:** The main transfer process runs via `systemd`. It is designed to start automatically on boot and restart automatically if it crashes.
2. **Web Report Server:** A separate lightweight web interface allows users to view upload history via a browser.
   - **URL:** `http://<server-ip>:5050` (default port).
   - **Access:** Browse to the URL to see the upload history dashboard.
3. **Manual Testing:** Developers can manually trigger specific components using CLI scripts.

## Main Workflows

### 1. Automated Asset Transfer (Daemon Mode)
This workflow runs continuously in the background.

1. **Detection:** The daemon polls Box folders (PROD, EDU, QA) every 5 minutes (configurable) for new ZIP files.
2. **Download:** Upon detecting a new file, it downloads the ZIP to local temporary storage.
3. **Upload:** It connects to the GECHUB SFTP server using dual-factor authentication and uploads the file.
4. **Archival:** If the upload is successful, the file is archived in Box.
5. **Logging:** The event is recorded in the local SQLite database (`upload_history.db`).
6. **Notification:** An email is sent to the designated recipients if the operation succeeds or fails.

### 2. Viewing Upload Reports
Users can view historical data about asset transfers.

1. **Start the Report Server:**
   ```bash
   python report_server.py
   ```
   Ensure the `UPLOAD_HISTORY_DB` environment variable points to the correct SQLite database path.
2. **Open Browser:** Navigate to `http://localhost:5050`.
3. **Filter Data:** Use the date range selectors to filter uploads by environment (PROD, EDU, QA) and status (Success, Failed, etc.).

### 3. Generating Email Reports
A weekly email report can be generated manually or via Cron.

1. **Manual Execution:**
   ```bash
   # Default: Last 7 days
   python report_email.py

   # Specific Date Range
   python report_email.py --start 2026-04-01 --end 2026-04-14
   ```
2. **Cron Job:** Configure `cron` to run the script weekly (e.g., every Monday at 8 AM UTC).

### 4. Manual SFTP Testing
Use the test script to verify credentials and connectivity before running the full workflow.

1. **Create a Test File:**
   ```bash
   echo "test" > test.zip
   ```
2. **Run Test Script:**
   ```bash
   python test_sftp_upload.py --env prod --file test.zip
   # Or test all environments:
   python test_sftp_upload.py --all --file test.zip
   ```

## FAQ

**Q: Why is my file not uploading?**
A: Check the `report_email.log` or system logs for errors. Common causes include:
- Incorrect SFTP credentials in `.env`.
- Box API rate limiting.
- Temporary SFTP server outage (the system retries automatically with exponential backoff).

**Q: How are emails handled during outages?**
A: The system uses rate-limited alerts. If Mailgun or the SFTP server is unavailable, it prevents email spam by coalescing notifications until the service recovers.

**Q: Where is the data stored?**
A: All upload history is stored in a local SQLite database named `upload_history.db` located in the project directory.

**Q: Can I change the polling frequency?**
A: Yes, modify the `POLL_INTERVAL_SECONDS` variable in your `.env` file.

**Q: What happens if the server reboots?**
A: The daemon is configured for `systemd` integration, so it will automatically restart after a reboot.