--- title: Purple Ingest Notifications slug: editorial/purple-ingest-notifications docTags: createdAt: 2025-11-13T11:49:24.723Z --- **User guide for configuring and receiving notifications from Purple Ingest.** # Overview Purple Ingest sends notifications to keep you informed about your content processing. **Always-On Notifications** (automatic when email addresses configured): - **Job Completion** - When content processing succeeds, fails, or completes with warnings - **Import Errors** - When file processing encounters validation or parsing errors **Optional File Alarms** (require `alarm.enabled: true`): - **File Received Alarm** - Sent immediately when an issue file is received and queued for processing - **Expected Issue Alarm** - Sent at expected date (before publication) when file hasn't been uploaded - **Missing File Alarm** - Sent at publication date when file still hasn't been uploaded All notifications are sent via email to addresses you configure per team. Currently, only email notifications are supported, but additional notification channels may be added in the future. # Configuration ## Adding Email Recipients To receive notifications, configure email addresses in your team's `config.yml` file: ```yaml emailAddress: - admin@example.com - team@example.com ``` **Key Points:** - `emailAddress`: List of email addresses to receive all notification types (required) - All notification types use the same recipient list - Multiple recipients are supported - Email addresses are sent via BCC for privacy (recipients don't see each other) - **Email addresses can only be configured at root level** - all paths use the same recipients - To enable file alarms, additional configuration is required (see Optional File Alarms section) For complete configuration file documentation, see the [Configuration Guide](#). # Notification Types ## Always-On Notifications These notifications are **sent automatically** whenever you configure email addresses. No additional settings are required - they work as soon as you add recipients to the `emailAddress` field. ### 1. Job Completion Notifications Sent when a content transformation job finishes processing. ### When Sent - **Success**: Job completed without errors - **Partial Success**: Job completed with warnings, issue is already published - **Partially Processed**: Job completed with warnings, issue not yet published - **Failure**: Job failed due to errors ### Email Content **Success:** - Import information (publication, issue, dates, files) - Link to Ingest Monitoring **Partial Success:** - Import information (publication, issue, dates, files) - General action items: - Open Ingest Monitoring to view detailed warnings - Review each warning to determine if action is needed - Verify content renders correctly despite warnings - Link to Ingest Monitoring **Partially Processed:** - Import information (publication, issue, dates, files) - General action items: - Open Ingest Monitoring to view detailed warnings - Review each warning to determine if action is needed - Verify content renders correctly despite warnings - Link to Ingest Monitoring **Failure:** - Import information (publication, issue, dates, input file) - Detailed error message explaining what went wrong - Link to Ingest Monitoring ### What to Do **Success notification:** 1. Verify the issue in Content Cloud 2. Confirm content renders as expected (only possible if the publication date is already reached) **Partial success notification:** 1. Open Ingest Monitoring to view detailed warnings 2. Review each warning to determine if action is needed 3. Verify content renders correctly in Content Cloud 4. Address any critical warnings for future uploads **Partial processed notification:** 1. Open Ingest Monitoring to view detailed warnings 2. Review each warning to determine if action is needed 3. Verify content renders correctly once published 4. Address any critical warnings for future uploads **Failure notification:** 1. Read the error message carefully 2. Check that the input file is valid and not corrupted 3. Review metadata or configuration for errors 4. Fix the issue and re-upload the file 5. Confirm success notification arrives after re-upload ### 2. Import Error Notifications Sent when file processing encounters validation or parsing errors. **When Sent:** - Immediately after file is processed (CSV, EPUB, NAME\_SCHEME, or SB\_ARCHIVE batch) - Sent if errors are detected during parsing, validation, or processing - For SB\_ARCHIVE: Sent once per batch with all errors from all processed folders - For EPUB: Sent for each file with errors (metadata extraction, validation, or configuration issues) **Email Content:** - Team ID and filename (or batch name for SB\_ARCHIVE) - Detailed list of all errors found (line numbers for CSV, metadata issues for EPUB, folder-specific errors for SB\_ARCHIVE) - Link to Ingest Monitoring **What to Do:** 1. Review each error carefully 2. Fix the errors in your file or metadata 3. Re-upload the corrected file 4. Confirm no error notification arrives after correction **Common Errors:** **CSV Collector:** - **Invalid date format**: Use supported formats (YYYY-MM-DD, DD.MM.YYYY, DD/MM/YYYY) - **Publication not found**: Ensure the publication exists in Purple Publish and name matches exactly - **Missing required columns**: Include folder, publication, issue name, publication date - **Duplicate entries**: Each issue name + publication combination must be unique - **Invalid access type**: Use `free`, `paid`, or `locked` **EPUB Collector:** - **Publication not found**: Ensure the EPUB title exactly matches an existing publication name in Purple Publish (or check your publication mapping configuration if using name mapping) - **Missing metadata**: EPUB must contain required Dublin Core metadata fields (dc\:title, dc\:date) - **Missing title**: EPUB must contain a valid `` element in package.opf - **Invalid date format**: Publication date in EPUB metadata must be valid - **Invalid EPUB structure**: ZIP file must contain a valid EPUB with package.opf file - **Corrupted EPUB metadata**: The package.opf XML file must be well-formed and parseable - **File processing errors**: Unexpected errors during EPUB processing (e.g., corrupted ZIP, S3 access issues) **NAME\_SCHEME Collector:** - **Invalid filename pattern**: Filename must match configured pattern - **Publication not found**: Publication code in filename must match existing publication **SB\_ARCHIVE Collector:** - **No METS XML found**: Each issue folder must contain a METS XML file with edition metadata - **Edition not found in METS XML**: METS XML must contain parseable edition information - **Invalid folder name format**: Folder names must follow pattern `YYYYMMDD_EDITION_SEQUENCE` (e.g., `20250115_ED1_0001`) - **No publication mapping**: Edition code from METS must exist in `publications` configuration - **Publication not found**: Publication name must exist in Purple Publish and match exactly - **No files for ZIP**: Issue folder must contain at least one file besides METS XML - **ZIP creation failed**: Check S3 permissions and connectivity ## Optional File Alarms File alarms confirm when files arrive and monitor for missing or late files. They **must be explicitly enabled** by setting `alarm.enabled: true` in your configuration. Unlike always-on notifications, file alarms require both email addresses and the alarm configuration. ### When Sent The three alarm types are triggered at different stages of the upload lifecycle: **File Received Alarm:** - Sent immediately when your file arrives and is queued for processing - One email is sent per upload. Re-uploading the same file triggers another email. **Expected Issue Alarm:** - Sent when expected date is reached (configured via `alarm.start`, default: 1 hour before publication date) - File hasn't been uploaded yet - Checked every 5 minutes - Only sent once per issue **Missing File Alarm:** - Sent when publication date is reached - File still hasn't been uploaded - Checked every 5 minutes - Only sent once per issue ### Configuration ```yaml emailAddress: - admin@example.com alarm: enabled: true start: 1h end: 24h ``` **Alarm Configuration Fields:** - `alarm.enabled`: Enable or disable file alarms (`true` or `false`) - `alarm.start`: Time before publication date when file is expected (e.g., `2h`, `30m`, default: `1h`) - `alarm.end`: Stop sending alarms this long after publication date (default: `24h`) **Time Format:** - `30m` = 30 minutes - `1h` = 1 hour - `2h` = 2 hours - `24h` = 24 hours **Important:** Alarm settings can only be configured at root level and apply to all paths within your team. ### Email Content **File Received Alarm** includes: - Import information (publication, issue, dates, input file name) - A short confirmation that your file has been received and is waiting to be processed **Expected Issue Alarm and Missing File Alarm** both include: - Import information (publication, issue, dates, input file name) - Action items to check: - Whether the issue has been created in your CMS - Whether the export to SFTP has been triggered - Whether the uploaded file has the correct name - Whether the file is in the correct folder - Link to Ingest Monitoring ### What to Do **File Received Alarm:** No action needed. This confirms your file has arrived. Watch for the Job Completion notification to learn whether processing succeeded. **Expected Issue Alarm or Missing File Alarm:** 1. Check if the file was actually uploaded to the correct folder 2. Verify the filename matches the expected name 3. Confirm the file is in the correct path 4. Check if the CMS export completed successfully 5. Upload the file # Email Format All emails include: - **Subject**: Clear indication of notification type and affected issue - **Import Information**: Publication, issue name, dates, and filenames - **Error/Warning Details**: Specific information about issues (when applicable) - **Action Items**: Checklist of steps to investigate or resolve - **Ingest Monitoring Link**: Direct link to view the job details Emails are sent in both plain text and HTML format for compatibility with all email clients. # Recipient Privacy - All recipients are sent via **BCC (Blind Carbon Copy)** - Recipients **cannot see** other email addresses - One email is sent with all recipients in BCC # Troubleshooting ## Not Receiving Notifications **Check Configuration:** ```yaml emailAddress: - your-email@example.com alarm: enabled: true start: 1h end: 24h ``` **Common Issues:** 1. **Email field is empty or missing** - Add at least one valid email address to root config 2. **Invalid email format** - Ensure emails contain `@` and valid domain 3. **File alarms disabled** - Check that `alarm.enabled` is set to `true` in root config 4. **Spam folder** - Check spam/junk folders for emails from `noreply@purplepublish.com` ### Receiving Duplicate Notifications **Possible Causes:** 1. **Same email in multiple teams** - Same email address configured in different team configurations 2. **Misconfigured email lists** - Email address appears multiple times in the same list **Solution:** - Review your team's root configuration file - Ensure email addresses are only listed once in the `emailAddress` field # Configuration Examples ## Basic Setup Single admin receives all notifications: ```yaml emailAddress: - admin@dailynews.com alarm: enabled: true start: 1h end: 24h ``` ### Team Setup Multiple team members receive notifications: ```yaml emailAddress: - editor@magazine.com - production@magazine.com - admin@magazine.com alarm: enabled: true start: 2h end: 24h ``` ### Multi-Path Setup All paths use the same email recipients from root configuration: **Root:** `team-id/config.yml` ```yaml emailAddress: - general@publisher.com alarm: enabled: true start: 1h end: 24h ``` **Note:** Email addresses and alarm settings apply to all paths. Use a shared email address or distribution list if you need different people to receive notifications for different content. See the [Configuration Guide](#) for details on other per-path configuration options (collector, convert, upload). ### Different Alarm Timings Adjust alarm windows based on your publication schedule: **Tight deadline** (e.g., daily publication): ```yaml emailAddress: - team@publisher.com alarm: enabled: true start: 1h end: 24h ``` **Longer window** (e.g., weekly publication): ```yaml emailAddress: - team@publisher.com alarm: enabled: true start: 2h end: 48h ``` **Note:** Since alarm settings apply to all paths, choose timing that works for your most critical publications. ### No Alarm Setup Receive job completion notifications but no file alarms: ```yaml emailAddress: - team@news.com alarm: enabled: false ``` # Best Practices ## Email Address Management ✅ **Do:** - Use team email aliases (e.g., `team-publishing@company.com`) - Include key stakeholders only - Use distribution lists for larger teams - Keep email list updated as team members change ❌ **Don't:** - Add personal emails that might become inactive - Include external partners without approval - Use catch-all addresses that might ignore alerts - Add too many recipients (keep it focused) ### Alarm Configuration ✅ **Do:** - Set `alarm.enabled: true` to receive file alarms - Set `alarm.start` based on your workflow (default is `1h`, but 1-2 hours is typical for customization) - Set `alarm.end` to stop alarms after reasonable time (default is `24h`) - Account for timezone differences in your publication schedule - Test with your actual publication schedule - Document expected dates in your configuration ❌ **Don't:** - Set `alarm.start` too early (causes false positives) - Set `alarm.start` too late (doesn't give time to react) - Set `alarm.end` too short (might miss late issues) - Ignore file alarms (they indicate potential issues) - Disable alarms without understanding the impact ### Response Workflow Summary | Notification Type | Priority | Action | | ------------------------ | --------- | ----------------------------------------------------------- | | **Success** | ✅ Low | Verify in Content Cloud | | **Partial Success** | ⚠️ Medium | Check warnings in Ingest Monitoring, verify published issue | | **Partially Processed** | ⚠️ Medium | Check warnings in Ingest Monitoring, verify when published | | **Failure** | 🔴 High | Fix error and re-upload | | **File Received Alarm** | ✅ Low | No action needed, informational confirmation | | **Expected Issue Alarm** | 🟡 Medium | Upload missing file | | **Missing File Alarm** | 🔴 High | Upload missing file urgently | | **Import Errors** | 🟡 Medium | Fix file/metadata and re-upload | # Support For issues with notifications: 1. **Check configuration** - Verify `emailAddress` field is set correctly and `alarm.enabled` is `true` for file alarms 2. **Check spam folder** - Emails from `noreply@purplepublish.com` 3. **Contact support** - Include team ID, issue name, and timestamp