Attaching Files to Emails

You can attach files to an email in several ways.

• You can attach files that are associated with a particular process.

• You can attach documents.

• You can attach files on a server.

You can specify attachments in the following ways:

• You can include a relative process path in the source of a Process Definition.

• You can specify a file attachment in a status handler within a Chain Definition.

• If you are sending email using RedwoodScript, you can use the Mail_Attachments parameter. This parameter accepts a comma-separated list of files.

Relative Process Syntax

To attach a process file to an email, you must specify its address. A process file address has two parts:

• The relative process, which identifies the process that is the source of the file. The syntax for this part is specified below.

• The file name.

How you specify these parts depends on how the email is being generated.

• If you are submitting the System_Mail_Send Process Definition directly or as a Chain Process, enter the relative process in the Relative Process field and the file name in the File field.

  

• If you are submitting the System_Mail_Send Process Definition as a Chain Process, you can dynamically specify both the Relative Process and the File. Or, you can simply enter the values.

  

• If you are sending email using the Mail Definition Type, you can enter both the relative process path and the file name on one line in the [Attachments] section of the Source field, using the syntax <process>:<file>.

Process Syntax

When specifying an email attachment using the <process>:<file> syntax (for the Mail Definition Type) or the Relative Process field (for System_Mail_Send), you can specify the process in the following ways.

• parent: Indicates the parent process.

• <step_name>, Job <n>: Indicates a Step by name and a Chain Process by its location within the Step. For example: Step 2, Job 6.
• Job <jobid>: Indicates the Chain Process with ID <jobid>. For example: Job 1234.

File Syntax

When specifying an email attachment using the <process>:<file> syntax (for the Mail Definition Type) or the Relative Process field (for System_Mail_Send), you can specify the file in the following ways.

• To attach a particular file, specify the name of the file. For example: stderr.log.
• To attach all files of a particular type, specify ?type= followed by a file type. For example:
  • ?type=log: Attaches standard error log files. For example: Job 6:?type=log.
  • ?type=output: Attaches standard output logs. For example: Job 6:?type=output.

Examples

# Body of email here
...

[Attachments]

# Attach output file from parent
Parent:stdout.log

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

# Attach output file named stdout.log from job with job ID 123456
Job 123456:stdout.log

# Attach all output files from that same job
Job 123456:?type=output

You can attach multiple files separated by semicolons. For example:

Step 2, Job 4:stderr.log;Step 1, Job 3:stderr.log

Note: Only plain text (text/plain), HTML (text/html) and XML (text/xml) files can be embedded in emails.

Changing Attachment File Names

To change the name of a file attached to an email, put the new name at the beginning, followed by the <process>:<file> value. For example:

NewAttachmentName.txt=step 2, job4:stdout.log

Attaching Part of a Process File

To attach part of a process file, use the following keywords.

• ?range: Lets you specify a range of line numbers. Negative numbers are counted backwards from the end of the file.
• ?search: Lets you search for the occurrence of a string in the file. By default, the line with the first occurrence is used.
• ?options: Lets you customize the search behavior:
  • WildCard: Use this keyword with a search string of * to specify a wildcard 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.

The syntax for these keywords is as follows.

<process>:<file>?search=<pattern>[?options=<option>[,<option>]*]]

Examples

# Body of email here
...

[Attachments]

# 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 line
Step 2, Job 4:stderr.log?range=-15,-1;Step 1, Job 3:stderr.log?search="caused by"?options=RangeResult,IgnoreCase

Attaching Files from the File System

For security reasons, if you want to attach a file from a computer's file system, you must first tell RunMyJobs that it's OK to attach them. You can do this by setting the /configuration/jcs/mail/accessiblepath registry entry to a JSON array of the allowed paths. To do so:

1. Navigate to Configuration > Registry.

2. Locate or create the /configuration/jcs/Mail/accessiblepath registry entry.

3. Right-click the /configuration/jcs/Mail/accessiblepath entry and choose Edit from the context menu.
4. In the Value field, enter an array of allowable paths, like so: ["/tmp","/var/folder"].
5. Click Save & Close.
6. Restart RunMyJobs.

Attaching Documents

You can attach a document to an email with the following syntax:

<name>=<full_path_of_document>

For example:

mydocument.txt=doc:mypartition:/myParentApplication/myChildApplication/MyDocumentTest.txt

Inline Attachments

You can use the _inline keyword to include the contents of a document inline in the email body.

There are two parts to this procedure:

1. Prefix _inline onto the beginning of the file reference in the [Attachments] section.

2. Use the file reference (with the prefix) in the body of the email, using the format ${inline_filename.suffix}.

For example:

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

[Attachments]
inline_stderr.log=Step 1, Job 1:stderr.log

Note: If you inline a file with characters outside the ISO-8859-1 charset, the process file must have a format that specifies the correct charset or characters will not be displayed correctly.

Generating File Names

If you need to attach multiple files with the same name, you can use the following two tags to differentiate the file names by appending numbers to their names.

• @{name} - Inserts the original name of the file.
• @{index} - A simple counter.

For example, this line will give each file from Step 2, Job 1 a unique name, so that they can all be attached to the same email.

# Attach all files from Step 2, Job 1
@{name}-@{index}.txt=Step 2, Job 1:*

Additional Examples

# Body of email here
...

[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}

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. You can customize this behavior by changing the Value for the /configuration/jcs/Mail/attachmenterror registry entry.