E-Mail Templates Administration screen

The E-Mail Templates Administration screen let you able to add, edit, delete and review your templates configurations.

The screen appears as follows:

The Approval Request tab let you able to setup the templates to apply for the e-mails notifying an approval request.

The Approval Reply tab let you able to setup the templates to apply for the e-mails notifying an approval reply.

The Service Desk Approvals tab let you able to setup the templates to apply for the e-mails notifying a Service Desk Approval Request.

When installing the app, if no customization is applied, the Approval Request and the Approval Reply emails follow the Default Templates.

You are able to configure e-mail templates per project and e-mail templates that can be associated to an Approval Mapping.

The Default Templates are applied on any project/issue type/Workflow Transition not associated to a specific template.

You are able to customize the Default Templates as well.

Upload e-mail icons

By default, the e-mail displays the following icon

The Upload E-mail Icon screen allows you to upload new icons and delete unused icons. 

In order to upload a new e-mail icon follow the steps below:

• Click Upload E-mail Icon on the top of the E-Mail Templates Administration screen

• choose the file to upload

Approval Request General Settings

The General Settings drop down list allows to customize

• the text displayed on the buttons appearing on the Approval Request email that allow to Approve, Reject. Abstain or Reset the approval

 This setting can be overwrite by an Email Template Button Texts specific settings.

 When no customization is specified, the email displays the texts Approve, Reject, Abstain, Reset.
E.g.
Button Texts setting

Email

• the text displayed on the new approval email sent case of wrong approval response. This email is sent case of the Approval Comment is mandatory and the approver replied without adding any comment.
  Case of no custom setting is applied, the email displays the text established by default. 
  E.g.
  Warning Message setting
  
  Email
  
  

Customize the Approval Request and the Approval Reply Default Template

If no template per Project or Workflow transition exists, the Approval Request and the Approval Reply emails follow the Default Templates.

You are able to customize the default Approval Request and the Approval Reply template.

The Approval Request and Approval Reply tabs include a Customize default template button that allow to navigate the Default E-mail Template Configuration screen
 

The Default E-mail Template Configuration screen let you able to manage the following settings:

• The Condition to prioritize emails

  

• The email subject

  

• The  email body

  Free Body Text 

  You are able to create a text obtained concatenating texts and issue fields. The available fields to customize the Free Body Text include: Project, Issue Key, Issue Summary, Source Workflow Status, Workflow Transition, Reporter, Assignee, Description, Priority, Issue Approval Id and Custom fields. Furthermore, you can choose  if the Free body text appears on the Bottom(Default) or on the Top of the email body.

  

Some examples of custom free body text: 

The email logo

The email header

The email footer

Show or Hide issue's data and Approve/Reject Instructions 

It includes the following information:

Customize Approve/Reject Instructions 

Button Texts

Customize texts displayed on the buttons of the email that allow to submit the approval response.

Selected Fields

The selected fields appears on the e-mail by following the same order displayed on the Field List.

Drag and drop a field to change the order it appears in the email.

By Default the option Show Empty Values is OFF. so, fields having an empty value are hidden by the email.

You are able to display a field also if its value is empty by turning the option Show Empty Values ON:

 The list of available fields include two options for the Attachments: 

• Attachment: the email body will include the ordered names of the attachments and each name will redirect to the attachment path in the Jira instance; furthermore, the files are attached to the email.
• Attachment Links: Same email body as above but the files are not attached to the email.

Capability to provide the approval response via Approval buttons

Button Placement

You can choose  if the Approval Buttons appear on the Bottom(Default) or on the Top of the email body.

Comment screen popped up

Furthermore, you can choose  if a screen requiring the Approval Comment pops up or not.

Require Authentication

Case of Authentication is turned OFF, when replying to an approval request via buttons, the application checks the information embedded in the email including the original recipient email address and the approval token that allows to identify unequivocally the specific required approval.

It is expected that the user receiving the approval request email doesn’t forward it to a different user. But, if the original email recipient forwards the email to another user, the new recipient will be able to provide the approval response instead of the effective approver.

The Require Authentication option provides an higher security level to the reply validation.

Case of Authentication is turned ON, when replying to an approval request via buttons, the application asks to insert the password associated to the Jira user matching the original recipient email address:

Linked Issues

This setting allows to enable displaying linked issues in the email body.

A list of issues linked to the current issue, grouped by Issue link type, will appear on the e-mail body.

For each linked issue, the email will include the following information:

• Issue Key
• Issue Summary

 Notice that the linked issues displayed on the email are the same that, when the concerned user login in Jira is able to display on the issue.

Ensure that the user receiving the email has browsing permission on the Projects at whom the linked issues belongs to.

Subtasks

This setting allows to enable displaying Sub-Tasks in the email body.

A list of sub-tasks will appear on the e-mail body.

For each sub-task, the email will include the issue Key and any additional field chosen via the Sub-Task Fields screen:

The email will display Sub-Tasks information as follows:

 Notice that the subtasks displayed on the email are the same that, when the concerned user login in Jira, he is able to display on the issue.

 You are able to restore the original Default Template by clicking Reset Default Template.

How to create an E-Mail Template

The Add E-Mail template button available on each tab of the E-Mail Templates administration screen allows to create new templates for the Approval Request, Approval Reply and Service Desk Approvals emails respectively.

In order to create a new email template follow the steps below:

• Click on Add E-Mail template and fill the fields Template Name(Required) and Project or Condition (both fields are optional). 

Case of Approval Request and Approval Reply templates you are able to create Templates not associated to any Project. Those templates can be applied to a specific Project/Issue Type/Workflow transition via the Approval Mappings. Administration screen.

Case of Service Desk Approvals templates you are able to create Templates per Project. The selection of a Project is required.

• Click Add

The screen will display the created template that you are able to update by clicking Configure

Configure an E-Mail Template

The E-mail Template Configuration screen let you able to setup the same setting mentioned above for the Custom Default Template:

• the  Condition to prioritize emails
• the email header
• the email subject
• the email header
• the email logo
• the information to display into the email body

Case of Approval Request templates you can choose to show/hide the Approval buttons by the email. If you choose to show the Approval buttons, the recipient can state the approval response by clicking the buttons that show up in the email instead of  replying to the email utilizing the expected Approval tags.

Case of Service Desk Approvals templates you cannot choose to show/hide the Approval buttons  by the email; the Approval buttons shows up in the email always and the recipient can state the approval response exclusively via those buttons.

Editing an E-Mail Template

Click Edit to update the Template Name or to select/update the associated Project or to select/update the associated Conditional Rule. 

It's not allowed to create templates having the same name.

It's not allowed to associate two templates to the same Conditional Rule.

The Edit E-mail Template screen allows to select a Project or the condition enabling the template (you cannot fill both the fields). 

Deleting an E-Mail Template

Click Delete in order to eliminate the template definitively.

The application doesn't ask to confirm the action.

Copying an E-Mail Template

1. Click Copy  in order to create a new template from a copy of an existing one
    
2. Fill the fields  Template Name and Project showing up on the Copy E-mail template screen
    
3. Click Copy
4. The screen displays the created template that you are able to update by clicking Configure
   

Customize the text displayed on the buttons of the Approval Request email

In order to customize the text displayed on the buttons of the Approval Request email, you must follow the steps below:

• navigate on the Approval Request tab of the E-Mail Templates administration screen (Add-ons → Herzum Approval → E-Mail Templates → Approval Request tab)
  
  
• click the General Settings button in the top right of the screen
  
  
• insert texts no longer then 14 characters and click Add.

Service Desk Approval Email request notification and reply processing

Prerequisites

In order to enable the functionality, you must create a templates to apply for the e-mails notifying a Service Desk Approval Request.

You are able to configure Service Desk Approvals templates per Project by navigating on the Service desk approvals of the E-Mail Templates administration screen.

How the Service desk approvals reply works

The Service desk approvals reply can succeed via email by clicking on the Approve or Decline buttons and inserting valid credentials:

Notice that if the user is already logged in the Customer Portal, the Approve/Decline button will not redirect him to the Authentication form.

In this case the user will be redirected to the ticket waiting the approval response.

Recommendations

In order to avoid confusion between the native JIRA service desk Approvals required notifications and the Herzum JIRA service desk Approvals required notifications, we recommend to disable the JIRA service desk Approvals required notifications.

Common alerts advising of Service desk approvals reply failure 

Following you can find a list of alerts advising of a Service desk approvals reply failure and the cause:

• Authentication failed
  
  
  
  Cause: Wrong approver credentials (username/password)
  
  
• You don't have approve permission.
  
  
  Cause: The username inserted for authentication doesn't match any issue's candidate approver
  
  
• The operation can not be performed because the approval user <authenticating user> is different from the user <current logged in user> currently logged into the Jira/Servidesk session. Please logout from Jira/ServiceDesk.
  
  
  Cause: The username inserted for authentication doesn't match the username of the user currently logged in the customer portal or in Jira