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. By default, a notification email contains a link that lets the user sign in, view, and then complete the task.

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 links to perform an action on 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 links to perform an action on the task without having to sign in

  • 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:
  1. Open a process in the process editor.
  2. Select a task, click Menu Menu icon, and select Open Properties.
  3. Click Implementation and select the Notification tab.
  4. 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.
  5. 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.
  6. 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.
  7. Click Preview Preview icon 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.
  8. 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.
  9. 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:
  1. Open a process in the process editor.
  2. Select a human task, click Menu Menu icon, and select Open Properties.
  3. Click Implementation and select the Notification tab.
  4. 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.
  5. 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 Add icon 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 Options icon 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:

  1. Open a process in the process editor.

  2. Select a human task, click Menu Menu icon, and select Open Properties.

  3. Click Implementation and select the Notification tab.

  4. Click Add add icon next to Manage Email Templates.

    The Create an Email Template dialog box opens.

    Description of create_template.png follows
    Description of the illustration create_template.png

  5. Enter a name for your email template.

  6. 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 webform.png follows
      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 basic2.png follows
      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 basic1.png follows
      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}}

      The following table provides a description with examples of the formatNumber function in email templates:

      Function Description

      formatNumber

      Returns a comma separated string for a decimal number.

      Examples:

      {{#formatNumber}}7777.77{{/formatNumber}} is returned as 7,777.77

      {{#formatNumber}}-7777.77{{/formatNumber}} is returned as -7,777.77

      {{#formatNumber}}7777777.778{{/formatNumber}} is returned as 7,777,777.778

      Note that only decimal number is supported. Other data types, such as string or boolean, are not supported.

  7. Click Preview to view your template before finalizing it.

    Description of preview.png follows
    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:

  1. Open a process in the process editor.

  2. Select a human task, click Menu Menu icon, and select Open Properties.

  3. Click Implementation and select the Notification tab.

  4. Click Options Options icon next to the email template that you want to edit.

    The Edit Email Template dialog box opens.

    Description of preview_template.png follows
    Description of the illustration preview_template.png

  5. Edit the HTML markup as required.

    Alternatively, click Upload to browse for and upload an existing email template to replace the current one.

  6. Click Preview to view your template before finalizing it.