Using the Mail Definition Type

Unlike the simpler System_Mail_Send Process Definition, the Mail Definition Type lets you create advanced email-generation Process Definitions that can do the following:

  • Send formatted emails.

  • Use substitution parameters in email bodies.

  • Use RedwoodScript.

  • Use conditional expressions.

  • Change the content-type of an email.

Source Structure

You can use the Source field both to set the body of an email and to add sections that further configure the email.

Body

To define the body of an email, enter it at the beginning of the Source field. You can enter it in plain text or in HTML.

Configuration Sections

Following the body of an email, you can use the following keywords to create sections that further configure the email. Each section requires <variable>=<value> pairs.

  • [Attachments]: Lets you add multiple file attachments.
  • [Headers]: Lets you set email header fields, including Subject, cc, bcc, and reply-to.
  • [Body]: Lets you set metadata about the body, such as Content-Type and charset. Note that the chosen charset must be compatible with that of any inline attachments.

Note: By default, the Mail module uses the ISO-8859-1 charset., However, if the body of an email starts with <, the Content-Type is automatically set to text/html. If necessary, you can override this Content-Type in the [Body] section.

Note: If you attach process files, they must use a format that correctly identifies their charset.

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

For example, consider the following Source for an email:

Copy 
<html>
 <body>
    <p>This is the body of the email, created in HTML format.</p>
  </body>
</html>

[Headers]
# Use this section to set header fields.
subject=This is the subject of the email.

[Body]
# Use this section to configure the body of the email.
Content-Type=text/html; charset=UTF-8

[Attachments]
# Use this section to attach files.
stdout.log=Step 1, Job 1:stdout.log

Substitution Parameters

You can use the following substitution parameters in the email body or in the configuration sections.

  • ${jobname}: The description of the Process Definition.
  • ${jobid}: The ID of the process that sends the email.
  • ${partition}: The partition of the process, which is set to the partition of the Queue where the process is running.
  • ${<parameter_name>}: A Process Definition parameter. For example, if the Process Definition has a parameter named "param1", you can access it as ${param1}. This lets you use Redwood Expression Language in parameters, and include the output of the functions in the mail body.

For example:

Copy 
<html>
 <body>
    <p>This email was sent by ${jobid}.
  </body>
</html>

[Headers]
subject=${Subject}

Using Redwood Expression Language

The Mail Definition Type supports calls to REL functions. The syntax is as follows:

[?=<class>.<method>(<parameters>)?]

  • <class>: This must be one of the following:
    • A prefix for built-in REL functions. For example, to use the built-in REL function Time.now(), enter [?=Time.now()?].
    • The name of a Library, specified using the format <partition>.<library_name>, 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

You can use conditional expressions in the email body and configuration sections. The syntax is as follows:

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

  • <conditional_test>: The condition to test for. If the condition evaluates to true, the <text> is evaluated and inserted.
  • <text> - The text to insert if the condition evaluates to true.

For example:

Copy 
<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?]}

Conditional constructs can be nested, like so:

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

Note: There are no else or else if constructs.

Process Definition Parameters

The following special Process Definition parameters let you override defaults that have been set with the System_Mail_Configure Process Definition.

  • Mail_To: The email address to which the email is sent (required).
  • Mail_From: The sender of the email (optional).
  • Mail_Subject: The subject of the email (optional).
  • Mail_Server: The SMTP server to use for sending the email (optional).
  • Mail_Attachments: Lets you dynamically specify a comma-separated list of file attachments (optional).