Overview

Why The Special Handler Is Required

There are several ways of issues to be created and commented by your customers considering their inability to reach the Jira:

In this second variant, you won't be able to use the standard Jira mail handlers, as they require the sender to have a license to create, view, comment, add attachments, or transition issues. Using the Default Reporter option will make communication with your customers inconvenient. Users created through the standard mail handler will be added to the default group/s of the default JIRA application and will consume a license for this application. 

Relevant article: Creating issues and comments from email (Atlassian).

HelpDesk Mail Handler Specifics

HelpDesk Mail Handler is made on a base of the standard handler for creating issues and comments. But it doesn't check the user access to Jira (license) and in case of new user creation, this user will be added to any Jira user group(s) of your choice (not only license-consuming ones).

Ensure that HelpDesk superuser and those customers you want to create issues and comment on them have the relevant project permissions.

HelpDesk Mail Handler overcomes one of the Jira bugs (JRASERVER-45296) and makes the inline images from emails displayed in Jira.

As well as in Jira, you should avoid the special symbols in the attachments' names. Also, according to the ticket JRASERVER-2169, if the inline attachments have the same name, they both will refer to the latest attachments with this name.

Setting Up

Navigate to Jira Administration → System → Incoming Mail.

The HelpDesk Mail Handler should be applied just the same way as a standard mail handler in Jira. You will be able to select it in the list of mail handlers available in your Jira.

Relevant articles:

Available Handler Options

The following list contains the available settings. You can get more details on the standard ones ((plus)) in the following documentation: Create a new issue or add a comment to an existing issue (Atlassian).

Setting NameStandardDescription
Project(plus)Default project where new issues will be created.
Issue Type(plus)Default issue type for new issues.
New User Group

Default group for the new-created users. Here you can specify a group for your customers to automatically give the newcomers the customers' permissions.

Set different incoming mail addresses and the different handlers for them if you need to separate your new-coming customers (and their permissions) by some parameters.

Regexp to filter attachments

Emails may contain unnecessary attachments without extensions. Use this option to get rid of them.

Type in regular expression to filter all files without extension

^([^.]+)$
CODE

To filter all attachments with a specific name (for example for JIRA-generated files) use the following regular expression:

.*[jira-generated|atlassian].*
CODE
Filter embedded images

If specified, the embedded images up to a particular size (see the next setting) will be deleted.

If the Handler deletes any attachment from the comment it will inform about it at the end of the comment: "The following attachments were deleted:"

Filter embedded images by size (Kb)All embedded images up to this size will be deleted if the Filter embedded images option is selected.
Images typesAll embedded images of these types will be deleted.
Field to store E-mail cc

Some customers think that we communicate with them via email. Users think that they involve colleagues in a discussion of the issue when they put them into the CC field. In fact, we do not see the address from the copy. Select a custom field of the Text type to store emails from CC participation in messaging

(warning) Fetches values only on issue creation.

Use CC to User Picker setting to add extra addressees to issue as participants instead.

Field to store Email TOs

The same as above but for TOs field. Just in case Jira is not the main addressee but the CC-addressee.

Use TO to User Picker setting to add extra addressees to issue as participants instead.

Address to checkSpecific email address to perform the separate action with.
Address action

Specific action to be performed for emails from the Adress to check option:

  • Reject email
  • Create an issue from email (you can specify the different project and issue type in the options below)
Project for addressThe project where the new issue to be created for the address specified above.
Issue type for addressThe issue type to be created for the address specified above.
Strip Quotes(plus)If checked quoted text is removed from comments.
Split RegexA regular expression matching the text that separates the content of the email message mail body from other (replied or forwarded) content in the body.
The default value for issues with empty subjectThis value will be set as an issue Summary for the emails with an empty subject.
Catch Email Address(plus)If set, only emails having the specified recipient in fields To, Cc or Bcc will be processed.
Bulk(plus)Action that will be performed for emails with the 'Precedence: bulk' or emails with an 'Auto-Submitted' header that is not set to "no".
Forward Email(plus)If specified, then if this mail service is unable to handle an email message it receives, an email message indicating this problem will be forwarded to the email address specified in this field.
Accept comments from unregistered usersIf specified, then this mail service is able to handle comments from unregistered users.
Comment authorThe username of a default commenter, which will be used in case of comments from an unregistered user.
Create Users(plus)If a message comes from an unrecognized address, create a new Jira user with the user name and email address set to the 'From' address of the message. The password for the new user is randomly generated, and an email is sent to the new user informing them about their new account in Jira.
Default Reporter(plus)The username of a default reporter, which will be used if the email address in the From field of any received messages does not match the address associated with that of an existing Jira user
Notify Users(plus)If Create Users is set and Notify Users is checked new Jira users will receive a notification that their account has been created via email.
CC Assignee(plus)

Works only for new issue creation from email.

If selected, the first user from copy (CC) becomes the assignee. (warning) Note that this will not work for the unlicensed users.

CC Watchers(plus)

Works only for new issue creation from email.

If selected, each user from copy (CC) will become a watcher of the created issue. (warning) Note that this will not work for users without access to the issue.

TO to User Picker

Works only for new issue creation from email.

Select a field of User Picker (multiple users) type to add additional (besides Jira) addresses to this field as users. If you want to a there anybody from TO – not only those users who already have accounts in your Jira – check the Auto-create users for new emails option. The new users will be added to a group for new users.

CC to User Picker

Works only for new issue creation from email.

Select a field of User Picker (multiple users) type to add addresses from copy to this field as users. If you want to a there anybody from CC – not only those users who already have accounts in your Jira – check the Auto-create users for new emails option. The new users will be added to a group for new users.

Auto-create users for new emailsIf selected, a new Jira user will be created for each of the users from CC or TO with an unrecognized address. The new users will be added to a group for new users.
Skip senders project permissions

If enabled, only the HelpDesk superuser project permissions to be taken into account while creating/commenting an issue. So it won't matter if the real sender has the rights to create or comment issues. If disabled, both – HelpDesk superuser and the real sender – should have the relevant project rights to create or comment an issue.

Known Issue: if disabled and the real sender doesn't have the rights to comment an issue but the HelpDesk superuser does, the comment will be created from the HelpDesk superuser.

Outlook attachments reference management

Jira uses to manage the comments come from Outlook the following way:

  • it automatically collects all images to the issue attachments
  • it replaces the image with the [cid:] reference in the comment

That's why you can see something like that in the comment:

cid example

If you would like to avoid such attachment references to be created in the comments, tick the Turn on the filtering of [cid:] messages from comments checkbox in Helpdesk Settings → Customer Area → General Settings.

Tips & Tricks

The HelpDesk Email Hander has so many settings that it might be challenging to set it up. The following are several scenarios of incoming mail handling.

'Collective' issue creating

An issue can only have one author, but what if your customer wants to instantly share the new request with his/her coworkers?

  • Add the User Picker (multiple) custom field type to the relevant type of issue and name it Participants. The list of additional request participants (Jira users w/o licenses) from the customer side will be stored here.
  • Check that all users added to Participants will have/get access to issues (Browse Project permissions and Issue Security level).
  • Add them to the notification scheme if required (for example, to notify on issue comments and resolution).
  • Select the Participants field in the TO to User Picker CC to User Picker to automatically fill the field with those your customer want to share the request with.

You can control if Participants should include only the existing in your Jira users or just everyone your customer will address the request. For the second case, select the Auto-create users for new emails option in HelpDesk Email Handler.

You can restrict the User Picker (multiple) fields by particular groups or project roles. Helpdesk email Handler respects this restriction and won't add those users who don't meet the field configuration restrictions.

Just good to know extra addressees

Sometimes you don't need extra addressees to participate, yet it will be good to know to whom the request was sent additionally.

  • Add the Text field (single line) custom field type to the relevant type of issue and name it Extra Addressees. The list of emails will be stored here.
  • Select the Extra Addressees field in Field to store E-mail CCs / Field to store Email TOs to automatically fill the field with emails of those your customer want to share the request with.