Customize Notification Emails for Human Tasks

Keep your users informed about their task assignments and the progress of a process. You can easily configure notification emails for human tasks and create templates for those notifications.

Topics:

About Notification Email and Templates

You can configure Process to send a notification email to the task assignee when an event such as assignment, approval, escalation, reminder, and reassignment occurs. A notification email contains outcomes defined for a task, such as Approve or Reject. Assignees can click on these outcomes to complete tasks using their email clients, without having to sign in to the application.

Note:

After you configure the email notifications in design time, you need to enable the email notifications in runtime, see Enable Email Notifications. You can then view the notification logs and also resend email notifications to all or some of the original recipients, see View and Resend Email Notifications.

You can also configure and use customized notification emails for human tasks. You have an option to create customized email templates that include the following information:

Payload
Task
Links to perform an action on a task
Task comments

About Actionable Emails

You can configure a notification email with or without actions. An email with actions contains outcomes defined for a task, such as Approve or Reject. You can click on these outcomes to act on the task using your email client. In addition, you can add comments and attachments to the task.

WARNING:

Any user who has access to the email can perform the action so be careful who the notification email is sent to.

About Default Email Templates

If you enable email notification for a human task, you can either select a default template or create a new one for your use. By default, the following two email templates are available:

Default (With Actions) – Contains outcomes defined for a task, such as Approve or Reject. You can click on these outcomes to act on the task using your email client, without having to sign in to the application. In addition, you can add comments and attachments to the task.
Default (No Actions) – Contains a link that lets the end user sign in to the application, view the task, and complete it. If the end user is viewing the email on a mobile device and clicks the link, then the mobile app launches by default, if it’s installed.

Configure Email Notifications

Configure email notifications and specify when an email is sent to the task assignee. You can also customize email notifications so they contain all the information recipients need to easily recognize and act on them.

To configure email notifications:

Open a process in the process editor.
Select a task, click Menu , and select Open Properties.
Click Implementation and select the Notification tab.

Description of the illustration email_notification_new.png

Note:
If you’ve configured the human task to use an external UI instead of a web form, the options to include the form as image, PDF, or inline are not available on the Notification tab.
If needed, disable or re-enable email notifications. Note that notifications are enabled by default. Note that disabling the notification for a task won't disable reminder, escalation, or expiration emails. Instead, the selected email template will be used for those events.
In the Email Template field, select an email template that you want to use for the task-related emails.

Note:
The email template you select here is also used for reminder, escalation, and expiration emails.
Specify when the email notification is sent, for example when a task is assigned or completed, or when an error occurs. By default, On Assignment, On Completion, and On Error are selected. Use the drop down to determine the template for each notification email. The Use Parent Template is selected by default.
The parent template uses the template you selected before. You can either use the same template or select any other template. To manage email templates, see Manage Email Templates.
Click Preview to see what the subject will look like in your Inbox.
You can edit the subject line of the emails using valid payload attributes. See Payload Examples.
From the Include as Email Template options, optionally specify attachments to include with the email. You can include the form as an image attachment, a PDF attachment, or within the email (Inline).

Note:
If you encounter issues with displaying form as an inline image in your email client, use a custom email template that includes the form payload data. This way, task assignees are able to view the required content or data and act upon the task accordingly, without having to log in. The format for adding payload to your custom template is detailed here: Payload Examples.
Optionally, you can select Task Attachments to include files that users have uploaded to tasks.

Manage Email Templates

Use a customized notification email for human tasks that includes basic task information, form payload values, and comments, and that optionally lets end users perform a task action without having to sign in to the application. Create customized notification emails using the Notification options in the Properties pane.

To assign an email template to a human task:

Open a process in the process editor.
Select a human task, click Menu , and select Open Properties.
Click Implementation and select the Notification tab.

Description of the illustration manage_email_-1.png
If needed, disable or re-enable email notifications. Note that notifications are enabled by default. To disable, select the Disable notification check box to stop email notifications during task assignment. Note that disabling the notification for a task won't disable reminder, escalation, or expiration emails. Instead, the selected email template will be used for those events.

In the Email Template field, select an email template that you want to use for the task-related emails.

Optionally, create a new email template for your use. Click Add to the right of Manage Email Templates. See Configure Email Templates.

Description of configure_email.png follows
Description of the illustration configure_email.png

Optionally, copy, edit, preview, or download an existing email template for your use. Click Options to the right of the email template that you want to use.

Description of options_menu.png follows
Description of the illustration options_menu.png

Available options include:

Option	Description
Preview	Open the email template in the Preview Email Template dialog. You can view how the email appears to end users. The payload information isn't displayed in the Preview mode.
Copy	Copy and save the email template with another name.
Download	Download and save the email template in HTML format to your local drive or select an application to open the file.
Edit	Open the Edit Email Template dialog. You can edit your template in the code editor or browse for and upload a template from your local drive. You can also preview the template before finalizing it. This option isn't available for the default template.
Delete	Delete the email template. This option isn't available for the default template. Important: Deleting a template that is currently in use deletes all references to the template.

Configure Email Templates

Create customized email templates and use them to send notification emails for human tasks. Upload email templates from your local drive, edit or copy existing email templates, or download email templates for your use.

Create an Email Template

You can create email templates by uploading a file with an HTM or HTML extension, or manually entering the HTML markup directly into the code editor provided in the Create an Email Template dialog box.

To create a new email template:

Open a process in the process editor.
Select a human task, click Menu , and select Open Properties.
Click Implementation and select the Notification tab.
Click Add next to Manage Email Templates.

The Create an Email Template dialog box opens.

Description of the illustration create_template.png
Enter a name for your email template.

Use one of these options to create your email template:

You can click Upload to browse for and add an existing email template. You can then edit its contents.

Alternatively, you can start from scratch by manually entering the HTML markup for your email template. To include data, you’ll use mustache templates. Mustache templates are logic-less and work by expanding tags in a template using values provided in an object—the task object in this case. These templates provide an easy way to include data references in an HTML file. The following example shows how to reference the first name and last name using the mustache template:

Template:

<p>Hello {{first_name}} {{last_name}}</p>

Object:

{
          "first_name": "Joe",
          "last_name": "Smith"
        }

Output:

<p>Hello Joe Smith</p>

See Mustache and Mustache 5.

The following table provides a description of the task related attributes of the task object. Note that the variable names are case-sensitive.

Variable	Description
`acquiredBy`	Name of the user who has acquired the task
`acquiredById`	ID of the user who has acquired the task
`assignedDate`	Date when the task was assigned
`createdDate`	Date of creation of the task
`creator`	Creator of the task
`creatorId`	ID of the creator of the task
`dueDate`	Due date for completing the task
`endDate`	Date when the task must end
`fromUser`	Creator or user who reassigned the task
`fromUserId`	ID of the user from whom the task was acquired
`longSummary`	Detailed description of the task
`outcome`	Task outcome
`ownerGroup`	Group to which the task owner belongs
`ownerRole`	Role of the task owner
`ownerUser`	User who owns the task
`ownerGroupId`	ID of the group to which the task owner belongs
`ownerRoleId`	ID of the role of the task owner
`ownerUserId`	ID of the user who owns the task
`priority`	Task priority
`payload`	Map of task payload
`priorityNum`	Priority number of the task
`shortSummary`	Short summary of the task
`startDate`	Start date of the task
`state`	Current status of the task
`taskId`	Task ID
`taskNumber`	Task number
`taskDefinitionId`	Definition ID of the task
`title`	Title of the task
`updatedBy`	Name of the user who has updated the task
`updatedById`	ID of the user who has updated the task
`updatedDate`	Date when the task was updated

The following table provides a description of the process related attributes of the task object:

Variable	Description
`instanceId`	ID of the process instance in which the task is present
`processId`	ID of the process in which the task is present
`processName`	Name of the process in which the task is present
`processVersion`	Version of the process in which the task is present

The following table provides a description of the application related attributes of the task object:

Variable	Description
`assignee`	Full name of the task assignee
`currentYear`	Current year
`logo`	Oracle logo
`url`	URL for accessing the task details in runtime

The following table provides a description of the comments related attributes of the task object:

Variable	Description
`comments`	List of comments
`commentStr`	Actual comment
`updatedBy`	Name of the user who updated the comment
`updatedDate`	Date the comment was updated

The following table provides a description of the action related attributes of the task object:

Variable	Description
`actionDisplayName`	Display name of the action. For example, Approve, Reject.
`actionName`	Name of the action defined in human task action. For example, APPROVE, REJECT. Note that the action name is case sensitive and must match the task outcome.
`actions`	List of actions.
`url`	URL for performing the action.

Examples:

The following table provides examples of how to define tags using mustache templates:

To define a…	Example
Variable	`{{title}}, {{assignee}}`
Section/List	`{{#comments}} {{commentStr}} {{updatedBy}} at {{updatedDate}} {{/comments}}`
Null check	`{{#dueDate}} Due Date: {{dueDate}} {{/dueDate}}`
HTML string	`{{{actions}}}`
Payload	Use the camelCase naming convention for all business objects and form keys used in the payload to get the desired email template. Payload Example for a Form with Business Object `{{#payload}} {{#financialApprovalForm}} <td valign="top">{{contractCategory}}</td> <td valign="top">{{creditLimit}}</td> {{#contractDataObject}} <td valign="top">{{customerName}}</td> <td valign="top">{{contractStartDate}}</td> <td valign="top">{{creditLimit}}</td> {/contractDataObject}} {{/financialApprovalForm}} {{/payload}}` You can view the structure of payload in the Data pane on the web form page. Description of the illustration webform.png Payload Example for a Form with Text and Boolean Data `{{#payload}} {{#travelRequestForm}} {{#form}} <td valign="top">{{name}}</td> <td valign="top">{{customerName}}</td> <td valign="top">{{totalAmount}}</td> <td valign="top">{{country}}</td> <td valign="top">{{city}}</td> <td valign="top">{{purposeOfVisit}}</td> {{/form}} {{/travelRequestForm}} {{/payload}}` To get the structure of the payload, see the incoming webform dataObject in the Data Association page of the human task. Description of the illustration basic2.png Payload Example for Form with Array Data and Business Object `{{#payload}} {{#basicForm}} {{#form}} <td valign="top">{{firstName}}</td> <td valign="top">{{lastName}}</td> {{#expensesItem}} <td valign="top">{{description}}</td> <td valign="top">{{amount}}</td> {/expensesItem}} {{/form}} {{#invoice}} <td valign="top">{{id}}</td> {{/invoice}} {{/basicForm}} {{/payload}}` Description of the illustration basic1.png
Actions	You can define actions using a string, a list, or a map. Actions as a string: In this case, actions are defined as per the default email. You can’t modify the look and feel of the links. For example: `{{{actions}}}` Actions as a list: Use it if you want to iterate over each action to modify the look and feel of links. The same setting is applied on all the links. For example: `{{#actionsList}} <a href="{{url}}"> {{actionDisplayName}}</a> {{/actionsList}}` Actions as a map: Use it if you want to customize each action link. For example: `{{#actionsMap}} {{#APPROVE}} <a href="{{url}}" style="background-color: green;”> {{actionDisplayName}}</a> {{/APPROVE}} {{#REJECT}} <a href="{{url}}" style="background-color: red;”>{{actionDisplayName}}</a> {{/REJECT}} {{/actionsMap}}`

Note:

In Mustache, by default all variables escape in HTML. If you want to render unescaped HTML in an email's subject (that is, with special characters), you need to use triple mustache, for example {{{title}}}, or use &, for example {{&title}}.

Click Preview to view your template before finalizing it.

Description of the illustration preview.png

Note:
In preview mode, the payload and action map sections don’t show the data.

The actual email looks something like this:

Description of email_final.png follows
Description of the illustration email_final.png

Edit an Existing Template

You can edit an existing template using the Edit Email Template dialog box.

To edit an existing email template:

Open a process in the process editor.
Select a human task, click Menu , and select Open Properties.
Click Implementation and select the Notification tab.
Click Options next to the email template that you want to edit.

The Edit Email Template dialog box opens.

Description of the illustration preview_template.png
Edit the HTML markup as required.

Alternatively, click Upload to browse for and upload an existing email template to replace the current one.
Click Preview to view your template before finalizing it.

Use Handlebar Helpers

Optimize the configuration of your email templates by using handlebar helpers. Add logic into your email templates by using conditional helpers. You can also use other handlebar helpers such as string, number, and date formats.

Conditional Helpers

Some common conditional function helpers with examples are listed in the table below:

Function	Description	Example
`eq`	Checks if two elements are equal.	This example shows how to modify an email's subject based on a task's outcome (approve or reject) `Task {{taskNumber}} created by {{creator}} is {{#eq outcome "APPROVE"}}approved successfully{{else}} rejected{{/eq}}`
`neq`	Checks if two elements are not equal.	This example shows how to compare a business object’s value and modify an email. `{{#eq outcome "APPROVE"}} <p>Hello {{payload.expenseApprovalForm.firstName}}, your expense report for payload.expenseApprovalForm.totalAmount}} was approved!</p> {{else}} <p>Hello {{payload.expenseApprovalForm.firstName}}, Sorry your expense report for {{payload.expenseApprovalForm.totalAmount}} was rejected!</p> {{/eq}} {{#neq payload.expenseApprovalForm.team "sales"}} Sorry, this item is only eligible for Sales team {{/neq}}`
`gt`	Greater than operator	The example below shows how to mark an email's subject as Important! if the total amount of an expense report is greater than $10,000. `{{#gt payload.expenseApprovalForm.totalAmount 10000}}Important!{{/gt}} Expense report by {{creator}} for amount {{payload.expenseApprovalForm.totalAmount}} for approval` The example below compares an array object's size and conditionally shows expense items only if the number of items is greater than 1. `{{#gt payload.expenseApprovalForm.items.length 1}} <h3>Expense Items</h3> <table> <thead> <tr> <th>Item</th> <th>Amount</th> </tr> </thead> <tbody> <tr> <td>item1</td> <td>400</td> </tr> <tr> <td>item2</td> <td>340</td> </tr> </tbody> </table> {{/gt}}`
`and`	Checks if two conditions are true	This example shows how to add a special category section into the email's content if the travel category is critical and if the traveler is an executive. `{{#and payload.travelApproval.isCritical payload.travelApproval.traveler.isExecutive}} <h3>Special Category Traveler</h3> {{else}} <h3>Normal Traveler</h3> {{/and}}`

String, Date, and Number Format Helpers

Some common string, date, and number format helpers with examples are listed in the table below:

Function	Description	Example
`capitalizeFirst`	Capitalizes the first character of the value.	`<pre> {{capitalizeFirst value}} </pre>` If value is "string.example", the output will be "String.example".
`center`	Centers the value in a field of a given height.	`<pre> {{center value size=19 [pad="char"] }} </pre>` If value is "String.example", the output will be " String.example ".
`cut`	Removes all values of arg from the given string.	`<pre> {{cut value [" "]}} </pre>` If value is "String with spaces", the output will be "Stringwithspaces".
`join`	Joins an array, iterator or an iterable with a string.	`<pre> {{join value " // " [prefix=""] [suffix=""]}} </pre>` If value is the list ['a', 'b', 'c'], the output will be the string "a // b // c".
`lower`	Converts a string into all lower case.	`<pre> {{lower value}} </pre>` If value is 'String Helper Example', the output will be 'string helper example'.
`upper`	Converts a string into all upper case.	If value is 'Hello', the output will be 'HELLO'.
`replace`	Replaces each substring of a string that matches the literal target sequence with the specified literal replacement sequence.	`<pre> {{ replace value "..." "example" }} </pre>` If value is "String ...", the output will be "String example".
`dateFormat`	Returns the date in the specified format. Parameters: full long medium short pattern	`<pre> {{dateFormat date ["format"] [format="format"][tz=timeZone\|timeZoneId]}} </pre>` Examples: {{dateFormat date ["full"]} output: Tuesday, June 19 2012 {{dateFormat date ["long"]} output: June 19, 2012 {{dateFormat date ["medium"]} output: Jun 19, 2012 {{dateFormat date ["short"]} output: 6/19/12
`numberFormat`	Returns the number in the specified format. Parameters: integer percent currency pattern	`<pre> {{numberFormat number ["format"] [locale=default]}} </pre>`

Note:

Handlebars is a superset of Mustache and Mustache templates are compatible with Handlebars.

See Handlebars.