← Configuring Mail and Sending EmailsUsing the Mail Definition Type →

Customizing Emails

Using the System_Mail_Send you may attach one file and specify email headers, furthermore, the email is in plain text. With the mail definition type, you can customize the email to meet your needs.

By default, the email is in plain text, this can be overridden by starting the code with a <, in which case HTML is expected. You can specify the content-type in the [Body] section of the email, to set it to XML, for example.

note

The Mail Module requires the Module.Mail license key

note

The notification and alerting features of the Mail module require you to configure every job chain that is to use these features. If you make extensive use of alerts and/or notifications, Redwood recommends the Active Monitoring module, as you can configure alerts and notifications centrally.

Parameters

The following special parameters are used to send the email, they override the system defaults you set with the process definition System_Mail_Configure:

  • Mail_To - addressee of the email (required).
  • Mail_From - sender of the email (optional).
  • Mail_Subject - subject of the email (optional).
  • Mail_Server - SMTP server to use for sending the email (optional).
  • Mail_Attachments - parameter to dynamically specify a comma-separated list of file attachments (optional).

Syntax

The mail definition type has the following sections:

  • [Attachments] - File attachments including metadata (content-type, charset) are specified here.
  • [Headers] - For email headers.
  • [Body] - Metadata about the body, like content-type and charset.

Blank lines and comments (lines starting with #) are ignored in the sections above.

You can use the following substitution parameters:

  • ${jobname} - The description of the process that sent the email.
  • ${jobid} - The jobid of the process that sent the email.
  • ${<parameter_name>} - The value of the parameter of the email process, for example, if the email process has a parameter Subject it would be referenced as ${Subject}. This allows you to use Redwood Expression Language in parameters and use the output of the functions in the mail body.

Use one of the following keywords for job:

  • Parent - the parent job
  • <step name>, Job <m> - specifying the step and chain process, the chains have to be in the same chain, for example Step 2, Job 6.
  • Job <jobid> - the process with ID <jobid>, for example Job 1234.

You specify the file as follows:

  • <name> - the name of the file, for example stderr.log.
    • inline_ - prefix to use for files to be embedded in emails, for example inline_stderr.log=Step 1, Job 1:stderr.log, you then specify ${inline_stderr.log}` in the email source where you want the file contents to be inserted, see Inline Attachments.
  • ?type - will attach all files matching the type.
    • log - log files contain the output of standard error, for example Job 6:?type=log.
    • output - output files contain the output of standard out, for example Job 6:?type=output.
note

Only plain text (text/plain), HTML (text/html) and XML (text/xml) files can be embedded in emails, XML files are printed directly as XML.

//output file from parent
Parent:stdout.log

//error log from Job 2 of step named "Step 1"
Step 1, Job 2:stderr.log

//output file named stdout.log from job with job ID 123456
Job 123456:stdout.log
//all output files from that same job
Job 123456:?type=output

Retrieve part of the file with the following keywords:

  • ?range - specify a range of line numbers, negative numbers are counted backwards ( from the end of the file).
  • ?search - search for the occurrence of a string in the file, by default, the line with the first occurrence is copied.
  • ?options - customize the behavior of search.
    • WildCard - Used with a search string of "*" to specify a wild card search.
    • Reverse - Returns the last line in the file matching the search string.
    • IgnoreCase - Performs a case insensitive search.
    • EntireLine - An entire line in the attachment must match the specified string.
    • RangeResult - Returns all lines that match the search string.
note

Multiple files can be specified separated by semicolons (;).

//Last 15 lines from job 4 of step named  "Step 2"
Step 2, Job 4:stderr.log?range=-15,-1

//first "caused by" line from the error log
Step 1, Job 3:stderr.log?search="caused by"

//last  "caused by" line from the error log
Step 1, Job 3:stderr.log?search="caused by"?options=Reverse

//all "caused by" lines, case-insensitive
Step 1, Job 3:stderr.log?search="caused by"?options=RangeResult,IgnoreCase

//first and last example in one go
Step 2, Job 4:stderr.log?range=-15,-1;Step 1, Job 3:stderr.log?search="caused by"?options=RangeResult,IgnoreCase

The following ant expressions can be used to generate the file name of attachments, especially when you use a regex expression:

  • @{name} - The name of the file to attach.
  • @{index} - A simple counter.

Attaching Files from the Server

For security reasons, you have to specifically allow the directories in which the files reside on the server to be able to attach them. This is done by setting the configuration entry Mail.AccessiblePath to be a JSON array of the allowed paths.

Behavior for Missing Attachments

By default, when the mail process encounters a missing attachment, an operator message and a log entry in stdout.log are created and processing continues as if nothing happened. This can be customized using the following registry entry:

/configuration/jcs/mail/attachmentError

ValueDescription
errorthe mail process will reach status Error when it encounters a missing attachment
OperatorMessagean operator message and a log entry in stdout.log are created and processing continues as if nothing happened (default)
nonea log entry in stdout.log is created and processing continues as if nothing happened

Procedure

  1. Navigate to "Configuration > Registry".
  2. Drill-down to /configuration/jcs/mail/AccessiblePath, if the registry entry does not exist, create it.
  3. Choose New > Registry from the context-menu of the AccessiblePath registry entry and give it a name and a value.
  4. Choose Save & Close.

Example

Allowing files in /tmp to be attached to emails

  1. Navigate to "Configuration > Registry".
  2. Drill-down to /configuration/jcs/mail/AccessiblePath, if the registry entry does not exist, create it.
  3. To create the AccessiblePath registry entry, choose New > Registry from the context-menu of the mail registry entry and name it AccessiblePath.
  4. Choose New Registry from the context-menu of the AccessiblePath registry entry and give it a name, enter ["/tmp","/var/folder"] into the value field.
  5. Choose Save & Close.

See Also

← Configuring Mail and Sending EmailsUsing the Mail Definition Type →