Customize the subject and body of file and load notification emails from System Settings. Saved changes apply to future live emails as well as test emails.
Choose a template
Open Administration → System Settings → Global, then find Email Templates in the email settings. Editing requires permission to save System Settings.
Tab | Used for |
File Received | Confirmation that a file was received. |
File Failed | File validation failure notices. Other processing or conversion alerts can use separate system templates. |
Load Success | Confirmation that a production load completed successfully. |
Load Fail | A failed production load attempt. |
Each tab has its own Subject, Body, test-recipient field, and Test button. These are global templates: changes apply to notifications for all clients that use that template.
Edit, test, and save
- Open the template tab you want to change.
- Copy the current Subject and Body into a backup text file before editing. You can paste these back if you need to undo a change.
- Edit the wording or variables. Keep the existing indentation and layout unless you intend to redesign the email.
- Enter your email address beside the Test button, then click Test. This sends an actual email using example data and your current edits.
- Check the result message and the received email. Check the subject, layout, variable values, and links.
- Click the settings Save button and wait for confirmation. Testing does not save your edits.
- Future live emails use the saved subject and body. No worker restart is required; previously delivered emails do not change.
Email must be enabled and delivery settings must be configured. A test uses sample data, not your most recently loaded file. For example, the test destination is an example path, so it will not demonstrate a replacement that only matches your real share path.
Pug basics
The Subject and Body fields use Pug, a text format that generates the email. You do not need to replace the whole template to change a sentence.
- Keep indentation consistent. It controls which lines belong inside a section.
- Keep quotes, commas, brackets, and parentheses balanced.
- In the body,
pstarts a paragraph,#{...}inserts a value into text, andp= ...displays an expression as a paragraph. - Keep the helper definitions near the top, including
mixin metadataandmixin failureDetails, if the body uses+metadata(...)or+failureDetails(...).
These examples use Pug's standard variable and attribute syntax. See Pug interpolation and Pug attributes.
Change the subject
For a load-success subject containing the original filename:
!= `Production Load Complete: ${file.fileName}`For a fixed subject with no variable:
| Production Load CompleteThe backticks in the first example are intentional. Keep ${file.fileName} inside them. The != form is used here for a plain-text subject; for variables in the HTML body, use the escaped forms #{...} or = ... shown below.
Change body wording or add a variable
p Your file has been loaded successfully.
p File: #{file.fileName}
p Sender: #{clientNode.name}When adding these lines to the existing template, indent them to the same level as the nearby paragraphs. Use #{...} or = ... for variable values in the body so characters in filenames and other values are escaped correctly.
Common variables
Variables are case-sensitive. A variable can exist in a live email but be empty for a particular file or absent from a particular notification type.
Variable | Meaning and availability |
file.fileName | Original filename. Used by default in the subject and Filename field; there is no automatic alias fallback. |
file.alias | Optional friendly file name. Use a fallback when it is empty. |
file._id | System file ID. |
file.recordCount | Input record count when available. This is not necessarily the number of records loaded or exported. |
file.byteSize | File size in bytes when available. |
file.belongsTo | ID of the owning client, brand, or title. |
client.name | Parent client's name, when that client is available. |
clientNode.name | Name of the owning client, brand, or title. |
run._id | Conversion run ID, when a run is available. Used in load notifications. |
run.environment | Run environment, such as PRODUCTION. |
run.output.filename | Output filename, when output information is available. |
run.output.directory | Output destination directory or prefix. Does not automatically include the bucket, hostname, or output filename. |
occurredAt | Notification-generation timestamp in UTC ISO format for load notifications. It is not a separate measurement of the exact transfer completion time. |
errors | Error-message array for load-failure notifications. |
convertValidation.errors | Validation error messages for File Failed. In load notifications this is a shared message wrapper, not a full validation report. |
Load notifications also receive event (load-success or load-failed), title, and an initially empty customBody. The full file, client, clientNode, and run objects are available, but nested fields are not guaranteed to exist. Use the guarded examples below for optional data. The receipt and validation templates do not guarantee a run object.
Use the alias, with the filename as a fallback
In the subject:
!= `Production Load Complete: ${file.alias || file.fileName}`In the body:
p File: #{file.alias || file.fileName}Or change just the Filename entry in an existing metadata line to:
['Filename', file.alias || file.fileName]That last example is one entry inside +metadata([...]), not a complete Pug line.
Add or remove a metadata field
The default template uses +metadata to display label/value rows. For example:
+metadata([['Filename', file.fileName], ['File ID', file._id]])To add the sender, add another bracketed pair:
+metadata([['Filename', file.fileName], ['File ID', file._id], ['Sender', clientNode.name]])To remove a row, remove its entire pair and the adjoining comma. The default helper displays Unavailable for an empty value. Keep the helper definition if you keep these calls.
Handle optional run/output information
if run && run.output
p Output filename: #{run.output.filename || 'Unavailable'}
p Destination: #{run.output.directory || 'Unavailable'}This avoids trying to read output information when no run/output object is available. See Pug conditionals.
Show a user-friendly destination path
A destination may use a path that is meaningful inside the application, such as:
/load/UNC_SHARE/dir1/CLIENT_AIf users access that share as //server/dir, you can replace the displayed root in the Load Success template. Find the existing Output filename/Destination metadata line and replace it with:
+metadata([['Output filename', run.output.filename], ['Destination', (run.output.directory || '').replace(/^\/load\/UNC_SHARE(?=\/|$)/, '//server/dir')]])Keep this line inside the existing if run and if run.output sections, at its original indentation level. Replace //server/dir with your actual user-facing share root.
The example displays:
//server/dir/Processed_ftp/CLIENT_AThe replacement only matches /load/UNC_SHARE at the start of the path and retains the remaining directories. Other destinations remain unchanged. This changes email text only; it does not change the upload/load location, mount, bucket, filename, or file access permissions. The User Friendly Output Root setting used for clipboard paths does not automatically rewrite this email field.
Add a link
To add a help or support link, insert a paragraph like this at the same indentation as neighboring content:
p
a(href='https://example.com/support') Contact supportReplace the example URL and link text with your own. Use a full https:// URL for web links. A network-share path is best shown as text: email clients may block or decline to open local/file-share links. Displaying a share path does not grant access to that share.
Recipients and reloads
Templates control what an email says. Recipient settings control who receives it.
- In Global Email Notifications, enable the matching flag for each global recipient.
- For client-associated recipients, enable the matching flag on the contact for the owning client, brand, or title, then save the client settings.
- Load Success and Load Fail are separate subscriptions. File Fail does not automatically enable load emails.
- Each completed Reload attempt sends its matching outcome notification to subscribed global and owning-node contacts, even if an earlier attempt failed with the same error. Duplicate addresses are combined.
- The Test button sends to the test address you enter; it does not verify that contact subscription settings have been saved.
Troubleshooting
What you see | What to check |
FAILED when testing | Check indentation, quotes, brackets, and optional fields. Restore your backup if needed, then test smaller edits. |
The variable name appears literally | Body variables need #{...} or = .... Dynamic subjects need the Pug expression and backticks shown above. |
A blank field or Unavailable | The example/live data may not contain that value. Check spelling and use a fallback or an if guard. |
Test shows edits, but live email does not | Save System Settings and wait for confirmation. Confirm that you edited the matching template tab. |
Friendly destination root does not appear in a test | The sample path does not match your real root. Verify the replacement against the intended real destination. |
One recipient does not receive the email | Check the matching global/contact flag, email address, client save, mail delivery settings, and spam folder. |