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.
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.
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.
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.
-
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.pngPayload 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.pngPayload 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}}
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.pngNote:
In preview mode, the payload and action map sections don’t show the data.
The actual email looks something like this:
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.
-
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)
|
neq |
Checks if two elements are not equal. |
This example shows how to compare a business object’s value and modify an email.
|
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.
The example below compares an array object's size and conditionally shows expense items only if the number of items is greater than 1.
|
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.
|
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. |
If value is "string.example", the output will be "String.example". |
center |
Centers the value in a field of a given height. |
If value is "String.example", the output will be " String.example ". |
cut |
Removes all values of arg from the given string. |
If value is "String with spaces", the output will be "Stringwithspaces". |
join |
Joins an array, iterator or an iterable with a string. |
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. |
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. |
If value is "String ...", the output will be "String example". |
dateFormat |
Returns the date in the specified format. Parameters:
|
Examples:
|
numberFormat |
Returns the number in the specified format. Parameters:
|
|
Note:
Handlebars is a superset of Mustache and Mustache templates are compatible with Handlebars.See Handlebars.