How To Use Pre-Processing Tasks

If you want to manipulate email message headers, this can be done through coded Pre-Processing tasks. Most tasks will fix a particular problem.

1 Step-by-step guide
2 Scripted Task Configuration
- 2.1 Test Case and Test Script
- 2.2 Velocity Context
3 Content Type Mapper PreProc task configuration
4 Notes about email headers:
5 Example Pre Proc Scripts
- 5.1 Replace From: Address
- 5.2 Extract address from name part and set as from address
6 Related articles

Step-by-step guide

Enable pre-processing tasks by going to Profiles-> Cog icon > Edit and check Use PreProcessed Message
Select the the tasks you want to enable.

Scripted Task Configuration

The Scripted Task allows you to change message with a Velocity script.

The objective of the scripted task is to modify the message before running the standard JEMHCloud process using a programmatic script. Even though Velocity is a template language designed to render UI, Emails, etc. it can be used to modify objects programmatically including the message. Velocity is the language selected to allow users customize email templates and this is another way to be used. Other tasks are to fix most common problems in received messages.

After enabling the task you will be able to write your own script. This tutorial will show several examples on how to modify a message. Please note this is an advance feature and minimal programming skill are necessary (you may learn here!). Some examples:

$taskUtils.getHeader($message, 'Change-Me-If-I-Am-In-The-Message').setValue('new value') // header is changed if it exists
$taskUtils.getHeaderOrCreate($message, 'Change-Or-Create-Me').setValue('new value') // header is changed or created replacing existing value
$taskUtils.getHeaderOrCreate($message, 'Update-Me').addValue('Add This Value') // header is changed or created adding a new value to existing value
$taskUtils.getHeader($message, 'Remove-Me').remove() // headers is removed
$taskUtils.getHeader($message, 'Remove-Me-Too').setValue(null) // headers is removed
$taskUtils.getHeader($message, 'Remove-Me').setValue('  ') // headers is removed
 
$taskUtils.getHeader($message, 'CC').remove() // Removes CC
$taskUtils.getHeaderOrCreate($message, 'To').addValue('add.me.as.email.user@mycompany.com') // Adds an email user to all the issues created/updated by email.
 
//A way to fix the encoding problem, replacing the problematic encoding (ISO-8859-8-x) in all the Content-Type headers in all mime parts to UTF-8 (Content Type Mapper Task is the recommended way to fix this problem)
#foreach ($header in $taskUtils.getHeaders($message, 'Content-Type', true)) // Second parameters defines which headers to be loaded. True means include sub-parts.
   $header.setValue($header.getValues().get(0).replaceAll('ISO-8859-8-x','UTF-8'))	
#end

Test Case and Test Script

A way to verify that your email is being modified as expected is creating a test script that tests your main script. The test script will assert how a test case email looks after the main script is executed. A test script is also written in velocity and it's composed of a list of assertions. An assertion is a condition that needs to be true in order to pass. You can verify that a given header has been removed, added or its value has been changed.

For example, if you're adding a email address to your emails

$taskUtils.getHeaderOrCreate($message, 'To').addValue('add.me.as.email.user@mycompany.com')

You can assert that the test case after being processed will have the new address in the To: header.

$assert.assertEquals('Fernando <fernando@mail.com>,add.me.as.email.user@mycompany.com', $taskUtils.getHeader($message, 'To').getValueAsCSV())

The processed email will have two to: addresses, the original email address and the one the script adds

If you remove the Date header:

The header must be null

The test case can be created from scratch or based on one of your normal test cases.

Have a look at the Velocity Context and the APIs to know the utility objects and methods Velocity scripts have available like $taskUtils and $assert.

You can test your script pressing the validate button or when you submit the profile configuration. A profile with failing assertions cannot be saved. It's highly recommended to test your script adding many assertions to verify it works properly. If an assertion fails, the error below the script editor will show you the line and column number in the script that is failing.

Velocity Context

You can expand the velocity context to find links to javadoc for published Java classes:

Content Type Mapper PreProc task configuration

Sometimes, email clients refer to the encoding of content within the email in such a way as to make it unprocessable by JEMHC /Javamail. Sometimes, it is because an illegal value is presented in the email, for example 7-bit which is not legal but 7bit is (see Oracle page referring RFC-2045 supported types). JEMHC can fix problems like this but they need to be configured:

Notes about email headers:

1) One header may have multiple values

aHeader.getValues() returns a list of String values, potentially including double quotes: [ "John Doe" <John@mail.com>, "Dave Doe" <dave@mail.com> ]

aHeader.getValueAsCSV() joins all the values together returning a simple String value, potentially including double quotes: "John Doe" <John@mail.com>,"Dave Doe" <dave@mail.com>

2) One header may appear multiple times in the email.

Commonly used multi-part mime messages structure an email in a recursive-tree form. Main part may be multi-part containing sub-parts like the text body, html body, attachments or other multi-parts. In this case each part and sub-part may contain the same header. The most common example is the Content-Type that defines the type of the (sub-)part.

In our example, $taskUtils.getHeaders($message, 'Content-Type', true) returns the list of all Content-Type headers any part level.

Example Pre Proc Scripts

Replace From: Address

This example shows how to manipulate the From: address, to detect one domain and swap it out for another.

Script

Example Email

Test script

Yes, it would be handy to show ‘debug’ render output where #if #else are used , https://thepluginpeople.atlassian.net/browse/JEMHC-2936 has been logged for this.

Proof

Processing Report

Here you can see the example mail processing report generated by JEMHC for our support project, a user would have been associated if it didn’t exist, in this case, we’ve simply created a new portal user:

Extract address from name part and set as from address

If you are receiving emails that are sent from a system address with a personal part that contains the actual sender address. The script below will extract the actual sender address from the original personal part and will set this value as the sender of the email to be processed correctly.

Example Script:

Example Test Case:

Test Script:

Proof:

Processing Report:

Here you can see the example mail processing report generated by JEMHC for this Test Case, a user would have been associated if it didn’t exist, in this case, we’ve simply created a new portal user: