Purple Ingest Notifications

26 min

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:

emailAddress:
  - [email protected]
  - [email protected]

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:

Verify the issue in Content Cloud

Confirm content renders as expected (only possible if the publication date is already reached)

Partial success notification:

Open Ingest Monitoring to view detailed warnings

Review each warning to determine if action is needed

Verify content renders correctly in Content Cloud

Address any critical warnings for future uploads

Partial processed notification:

Open Ingest Monitoring to view detailed warnings

Review each warning to determine if action is needed

Verify content renders correctly once published

Address any critical warnings for future uploads

Failure notification:

Read the error message carefully

Check that the input file is valid and not corrupted

Review metadata or configuration for errors

Fix the issue and re-upload the file

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:

Review each error carefully

Fix the errors in your file or metadata

Re-upload the corrected file

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 <dc:title> 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

emailAddress:
  - [email protected]

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:

Check if the file was actually uploaded to the correct folder

Verify the filename matches the expected name

Confirm the file is in the correct path

Check if the CMS export completed successfully

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:

emailAddress:
  - [email protected]

alarm:
  enabled: true
  start: 1h
  end: 24h

Common Issues:

Email field is empty or missing - Add at least one valid email address to root config

Invalid email format - Ensure emails contain @ and valid domain

File alarms disabled - Check that alarm.enabled is set to true in root config

Spam folder - Check spam/junk folders for emails from [email protected]

Receiving Duplicate Notifications

Possible Causes:

Same email in multiple teams - Same email address configured in different team configurations

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:

emailAddress:
  - [email protected]

alarm:
  enabled: true
  start: 1h
  end: 24h

Team Setup

Multiple team members receive notifications:

emailAddress:
  - [email protected]
  - [email protected]
  - [email protected]

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

emailAddress:
  - [email protected]

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):

emailAddress:
  - [email protected]

alarm:
  enabled: true
  start: 1h
  end: 24h

Longer window (e.g., weekly publication):

emailAddress:
  - [email protected]

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:

emailAddress:
  - [email protected]

alarm:
  enabled: false

Best Practices

Email Address Management

✅ Do:

Use team email aliases (e.g., [email protected])

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:

Check configuration - Verify emailAddress field is set correctly and alarm.enabled is true for file alarms

Check spam folder - Emails from [email protected]

Contact support - Include team ID, issue name, and timestamp