← Customizing EmailsMail Inbound User Guide →

Using the Mail Definition Type

The mail definition type allows you to create process definitions that send email.

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 chain definition 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.

You can use the System_Mail_Send process definition to send simple mails, but as soon as you want to customize the email, you can use the Mail Definition Type.

The definition type allows the use substitution parameters and allows you to change the content type of the email.

The Source of a mail process is composed of sections, which contain <variable>=<value> pairs. The default section is the body of the email and has no header; the following other optional sections can be used:

  • [Attachments] - File attachments are specified here
  • [Headers] - For email headers
  • [Body] - Meta-data about the body, like content-type and character-set (charset). Note that the chosen charset must be compatible with that of any inline attachments.

Blank lines and comments (lines starting with #) are ignored in the sections above. The contents of the default section is assumed to be the body of the email. If the default section starts with <, then the content type is set to HTML, you can override this in the [body] section.

You can use the following substitution parameters:

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

Calling RedwoodExpressionLanguage

The Mail definition type supports calls to REL functions.

Syntax

[?=<class>.<method>(<parameters>)?]
  • <class> - either:
    • Prefix for built-in REL functions, for example Time to call the built-in REL function Time.now(): [?=Time.now()?].
    • The Library of the REL function using the <partition>.<library_name> syntax, for example MyPartition.Custom_FunctionLibrary to call the function. You set partition to $ to use the partition of the process definition.
  • <method> - the method to be called, for example now().
  • <parameters> - the parameter(s) to the method, for example Europe/Paris in the built-in REL function Time.now(): [?=Time.now('Europe/Paris')?].

Conditional Expressions Syntax

The Mail definition type supports conditional constructs.

[?if test="<conditional_test>"?]<text>[?endif?]
  • <conditional_test> - condition to test for, if the condition evaluates to true, the <text> is evaluated and inserted.
  • <text> - text to evaluate and insert.

Conditional constructs can be nested as follows:

[?if test="<conditional_test>"?]<text>[?if test="<conditional_test>"?]<text>[?endif?][?endif?]
note

There are no else or else if constructs.

Example

<html>
 <body>
    <p>This email was sent by ${jobid}.
      [?if test="parameters=MyParameter ==='true'"?]Parameter <em>MyParameter</em> is set to <code>true</code>[?endif?]
      [?if test="parameters=MyParameter ==='false'"?]Parameter <em>MyParameter</em> is set to <code>false</code>[?endif?]</p>
    <p>Sent from [?=String.getSystemId()?].</p>
  </body>
</html>
[Headers]
Subject=[?=String.getSystemId()?]-${jobid}:[?if test="parameters=MyParameter ==='true'"?]true[?endif?]}

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)

Character Sets

You specify the charset for the email in the [body] section of your email. Note that the charset you specify must be compatible with any files you wish to embed in the mail text. When you embed JobFiles, these must use a format that correctly identifies their charset. By default, the Mail module uses the ISO-8859-1 charset.

Process File Attachments

You specify process files using the relative process syntax followed by a colon (:) and the file name (like <job>:<file>). Attachments can be specified in the source of the mail process definitions or using the Mail_Attachments parameter; the latter accepts a comma-separated list of files.

Specify the Job

Use one of the following keywords for job:

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

Specify the Files

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.

Retrieve Part of the File

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
<process_expression>:<file_expression>?range=<start-line>,<end-line>
<process_expression>:<file_expression>?search=<pattern>[?options=<option>[,<option>]*]
note

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

The following ant expressions can be used to generate the file name of attachments, especially when you use a GLOB expression (matching with * and ?) or the type keyword for the file name:

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

You can force an attachment to be inserted inline into the email, to form the email body, using the inline_ prefix. Note that only text, HTML, and XML files are supported, you then specify ${inline_stderr.log}` in the email source where you want the file contents to be inserted, see Inline Attachments.

note

When you insert a file with specific characters outside the ISO-8859-1 charset, the JobFile must have a format that specifies the correct charset or characters will not be displayed correctly.

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.

note

This option is not supported in cloud environments.

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

Document Attachments

You attach documents using the following syntax:

[inline_]<name>=<full_path_of_document>
  • inline_ - prefix used to include the document in the email body; requires ${inline_<name>} in the email body at the desired location of insertion.
  • <full_path_of_document> - full doc: URL to the document

Example

For the below example to work, the process definition needs to have a parameter TimeNow.

<html>
<body>
<h4>Latest financial results for board-members</h4>
<p>The financial results as of: ${TimeNow}</p>
<p>See attached <code>report</code> for a summary of the latest results.</p>
<br/>
<p>This message contains confidential and legally privileged information. In the event of any error in transmission,
unauthorized recipients are requested to contact the sender immediately and not to disclose or make use of this information.
No warranties or assurance are made or given as to the accuracy of the information given or in relation to the safety
of this e-mail and attachments. No liability whatsoever is accepted for consequences arising from this e-mail.</p>
<p>This email was generated by <em>${jobname}:${jobid}</em>.</p>
</body>
</html>

External Attachments

For the below example to work, the mail process definition needs parameters original_subject, Mail_To, TimeNow and InputFile, the latter is the file that was being processed by the chain (it must be available in /var/reports/inbox/ and accessible to the Mail module - see AccessiblePath ). The process needs to be in at least the third step, the first chain process of the first step must fail (reach status Error ) and have a Status Handlers set to Continue on Error, there must also be two more chain processes in the first step and a second chain process in the second step that produces output.

<html>
<body>
<h4>Process failed badly</h4>
<p>The time now is: ${TimeNow}</p>
<p>See attached <code>stderr.log</code> for details about the error.</p>
<i>This email was generated by ${jobname}:${jobid}.</i>
</body>
</html>

[Attachments]
#Attach stderr.log from job 1, on step named 'step 1'
error.txt=Step 1, Job 1:stderr.log
#Attach last 6 lines of stdlog.log from job 2, on step named 'step 1'
error.txt=Step 1, Job 1:stdlog.log?range=-6,-1
#Attach all files from Step 2, Job 1
@{name}-@{index}.txt=Step 2, Job 1:*
#Attach all log files from Step 2, Job 2
@{name}-@{index}.txt=Step 2, Job 2:?type=log
#Attach a file with all lines in "Step 1, Job 3:stdout.log" containing "caused by" (case-insensitive)
rootCause.txt=Step 1, Job 3:stdout.log?search="caused by"?options=IgnoreCase,RangeResult
#Attach multiple files from other processes, a file with all lines matching 'caused by' and all output files of a process
@{name}-@{index}.txt=Step 1, Job 3:stdout.log?search="caused by"?options=IgnoreCase,RangeResult;Step 1, Job 1:?type=output
#Attach a file from the server
Attachment.doc=/var/reports/inbox/${InputFile}

[Headers]
#set the reply-to address and override subject
reply-to=it@example.com
subject=Something went wrong, original subject: ${original_subject}

[Body]
Content-Type=text/html; Charset=UTF-8

Inline Attachments

Inline attachment example, this example needs a parameter named err_jobid which contains the ID of the process in error.

Hi,

Process ${err_jobid} failed.  The error message was: ${inline_stderr.log}

The procedure to follow is attached to this message in mydocument.txt.

[Attachments]
inline_stderr.log=Step 1, Job 1:stderr.log
mydocument.txt=doc:mypartition:/myParentApplication/myChildApplication/MyDocumentTest.txt

See Also

email mail

← Customizing EmailsMail Inbound User Guide →