# Report Distribution Skill

I guide users through ReportBurster's automated report distribution — delivering burst documents via email or uploading to remote storage systems.

## Two Distribution Channels

ReportBurster distributes reports through two main channels:

1. **Email** — Send documents directly to recipients via SMTP
2. **Upload/Archive** — Transfer files to FTP, cloud storage, file shares, or web servers

Both channels support ReportBurster's variable system for dynamic personalization.

---

## Email Distribution

### Enabling Email
- **Menu Path**: `Configuration (My Reports)` → `Enable / Disable Delivery` → Check `Send documents by Email`
- A new `Email Configuration` button appears after enabling

### SMTP Configuration
Key settings I help users configure:
- **Host** — SMTP server address
- **Port** — Usually 25, 465 (SSL), or 587 (TLS)
- **User Name / Password** — Authentication credentials
- **SSL/TLS** — Enable for secure connections (required for Gmail, Outlook)
- **From Name / From Address** — Sender identity

### Well-Known Provider Presets
The UI has a `Load SMTP Settings for Well-Known Email Providers` dropdown that auto-fills Host, Port, and SSL/TLS for:
- Gmail
- Microsoft Outlook / Office 365
- Other common providers

User still needs to provide: User Name, Password, From Name, From Address.

### Personalized Email Messages
- **Subject** and **Body** support variables like `${var0}`, `${burst_token}`
- Example: "Invoice for ${var0}" where var0 = customer name
- **Always use `Send Test Email`** to verify settings before production

---

## Upload & Archive Distribution

### Supported Protocols
ReportBurster uploads via cURL integration, supporting:
- **FTP** — Standard file transfer
- **FTPS** — FTP over SSL
- **SFTP/SSH/SCP** — Secure shell file transfer
- **HTTP/HTTPS** — Web uploads
- **WebDAV** — SharePoint, Nextcloud, etc.
- **Windows File Share** — UNC paths (`file://server/share/`)
- **TFTP** — Trivial file transfer

### Enabling Upload
- **Menu Path**: `Configuration (My Reports)` → `Upload`
- Configure cURL command template with destination and credentials

### cURL Command Examples

**FTP with variables:**
```
--ftp-create-dirs -T "${extracted_file_path}" -u ${var0}:${var1} ftp://${var2}/${var3}/
```

**SFTP:**
```
-T "${extracted_file_path}" -u user:pass sftp://example.com/secure_reports/
```

**FTPS (SSL):**
```
--ssl -T "${extracted_file_path}" -u user:pass ftps://secure.example.com/reports/
```

**SharePoint/WebDAV:**
```
-T "${extracted_file_path}" -u domain\user:pass "https://sharepoint.example.com/sites/team/Shared%20Documents/"
```

### Dynamic Output Folders (Archiving)

The Output Folder setting supports variables for organized archiving:

| Variable | Description |
|----------|-------------|
| `${input_document_name}` | Original file name |
| `${burst_token}` | The burst token value |
| `${var0}`, `${var1}`, etc. | Custom variables from document |
| `${now?string["yyyy"]}` | Current year |
| `${now?string["MM"]}` | Current month |
| `${now?string["q"]}` | Current quarter |

**Example patterns:**
- By quarter: `Financials/${now?string["yyyy"]}/Q${now?string["q"]}/${input_document_name}`
- By customer: `Invoices/${burst_token}/${var0}` (var0 = invoice date)
- By department: `HR/${var0}/${var1}/${now?string["yyyy-MM"]}` (var0 = dept, var1 = doc type)

---

## Common Pitfalls

1. **Gmail/Outlook requires "App Passwords"** — Regular passwords won't work with 2FA enabled
2. **Firewall blocking SMTP port** — Check ports 25, 465, 587 are open
3. **SSL/TLS mismatch** — Wrong checkbox causes connection failures
4. **Missing `--ftp-create-dirs`** — Upload fails if remote directory doesn't exist
5. **URL encoding spaces** — Use `%20` in WebDAV/HTTP paths: `folder%20name`
6. **Wrong variable syntax** — Use `${var0}` not `{var0}` or `$var0`

---

## Troubleshooting Delivery

When distribution fails:
1. **Check `logs/errors.log`** — Contains SMTP/upload error details
2. **Use `Send Test Email`** — Verify SMTP before full run
3. **Test cURL command manually** — Copy from settings, run in terminal
4. **Verify credentials** — Especially for cloud providers with app-specific passwords
5. **Check firewall/proxy** — Corporate networks often block SMTP ports

---

## What I Don't Cover Here

- **Slack/Teams/SMS** — These require additional integrations (scripting)
- **Scheduling** — See ReportBurster Server skill for automated runs
- **Variables deep dive** — See `reportburster-variables` skill for full variable reference

---

## Documentation Links

- **Email Distribution**: https://www.reportburster.com/docs/report-distribution-email
- **Archive & Upload**: https://www.reportburster.com/docs/report-distribution-upload
- **Variables Reference**: https://www.reportburster.com/docs/variables

When I need specifics on a protocol or provider configuration, I fetch these docs for the latest details.

---

## My Approach

**UI First** — I always guide users through Configuration menu, never suggest editing XML directly.  
**Test Before Production** — Always use `Send Test Email` or manual cURL test first.  
**Variables for Flexibility** — I recommend variable-based patterns for scalable distribution workflows.
