Configuration Reference

Owned by Boris Berenberg - Atlas Authority (Unlicensed)
Last updated: Nov 04, 2021
8 min read

This page will be broken out in the same format as the Mail Handler configuration screen and tabs.

 

Project

Handler Mode

  • Default behavior - Process emails into both new Issues, or Comment on an existing Issue.

  • Handling issues only - Process emails only into new Jira Issues.

  • Handling comments only - Process emails into only Comments.

    • In this mode, all Parser and Mapping configurations are ignored.

Matching an Email to a Jira Issue is a complex task. To accomplish this we look for a matching Issue Key in the email Subject, as well as leveraging Jira’s built in method provided at ServiceUtils.findIssueObjectInString
mailThreadManager.getAssociatedIssueObject

Project

Pick the project where new issues will be created. This setting CAN NOT be overwritten in the Mapping portion of the Mail Handler.

Issue Type

This has no impact if you configured the Handling comments only Handler Mode. If you configured it to Default behavior, and the email being processed is a comment, this section will not apply.

  • DYNAMIC_MAPPING - The Issue Type is set using the Mapping configuration further on in the Mail Handler.

  • <Issue Type Name> - New Issues are created in the selected Issue Type.

Reporter

This has no impact if you configured the Handling comments only Handler Mode. If you configured it to Default behavior, and the email being processed is a comment, this section will not apply.

You can hard-code a reporter here. If you leave this blank, then the Sender of the email is used as the Reporter. This mail handler will not create a new user for the reporter if they don’t have an existing account.

Assignee Options

  • First valid CC - The mail handler goes through the list of CC’d email addresses and assigns the newly created issue to the first email address that has access to the Project and created issue.

  • Reporter - The mail handler assigns the issue to the Reporter.

  • Project Lead - The mail handler assigns the issue to the Project Lead configured for the Project where the issue is being created.

  • Specified User - The issue is assigned to the user configured in the following Assignee field.

  • Unassigned - The issue is left unassigned.

Assignee

If the Assignee Options field is configured to Specified User then setting a user in this field will cause the Mail Handler to set them as the Assignee in the newly created issue. If Assignee Options is set to anything else, this field is ignored.

If you configure an Assignee in the Mapping portion of the UI, it will override this setting.

CC Watchers

If this is enabled, the Mail Handler will attempt to add all of the email addresses CC’d on the email to be Watchers on the newly created issue.

Attachment

Import attachments for issues

When checked, attachments from the email being processed are attached to the issue.

Import attachments for comments

When checked, attachments from the email being processed are attached to the issue.

Excl. Extensions

If you want to avoid specific extensions from being attached you can blacklist them here. For example if you want to block all exe files, you will enter exe here.

To truly blacklist exe you would need to add a number of entries:

exe Exe eXe exE EXe eXE ExE EXE

Max Size

If attachments are being processed, this setting helps you limit the maximum attachment size that should be processed. This is set in Bytes. The logic here is less than or equal to the number you specify.

Comment

Comment Option

  • Display - Attach the processed text as a comment.

  • No Display - Skip attaching the text as a comment.

Attach Email

This options allows you to attach the original email as an attachment to the Jira Issue.

  • As attachment, issues only

  • As attachment, for issues & comments

  • As attachment, for comments only

  • Disabled

Attach Email Note

Once configured, this portion will set a comment on any Issue where the Mail Handler attached the original Email as an Attachment.

The body of the comment may contain Macros.

This comment is made as the Reporter of the issue.

Parser

Parser

This setting configures which parser the Mail Handler uses to convert the email body into a set of variables and allows you to use those variables in the next Mapping section so that you can put the values into Fields.

  • JSON
    This is more like Key Value than it is JSON.

    title:"This is the summary" text:"This is the description" tags:"ma,fr" cftext:"this is value for custm field" cfselect:"SL1"

You can not have a space between the : and the first “ character.

  • XML

    <title>This is the summary</title> <text>This is the description</text> <tags>ma,fr</tags> <cftext>this is value for custm field</cftext> <cfselect>SL1</cfselect>

  • NONE

Mapping

Set mail-subject as issue summary

By setting the Summary field to @@MAIL_SUBJECT@@, the Subject of the email will be set as the Summary of the newly created issue. Text can be added around this handler-macro to annotate it further.

Set mail-body as issue description

By setting the Description field to @@MAIL_BODY@@, the Body of the email will be set as the Description of the newly created issue. Text can be added around this handler-macro to annotate it further.

Default

This section allows you to configure the default Field values.

Each row maps a Jira field to a default value.

Which fields are available depends on the Project and Issue Type selected in the Project tab.

X-Priority

This section allows you to configure how the Mail Handler sets the Priority of a newly created issue based on the various priority headers of the incoming email.

The incoming email’s priority is decided in this way:

  1. If the X-MSMail-Priority header is present, this value is used New in 5.3.0

  2. If the Importance header is present, this value is used New in 5.3.0

  3. If the X-Priority header is present, this value is used

Mapping

This section allows you to map content from the incoming email after it is processed by the Parser to Jira Issue Fields.

Each row maps a Jira field to the name of a mapping key that will be present in the email.

Post-Mail

Enable/Disable

When this box is checked, Jira will notify the below User that a new issue was created.

Include attachments

When this box is checked, the attachments from the original email that is being parsed are included this in this notification.

User(s)

Configure which users should be notified when a new issue is created.

Email Template

Configure which Email Template should be used to generate this notification.

Tagging

Tag created issues

If this checkbox is enabled, then all newly created issues will have a value set in the configured Text type Custom Field.

CF Text Field

Pick which Custom Field you want to have set on issue creation.

Value

Set the string that you want placed in the previously selected Custom Field. This can not be longer than 255 characters.

Security

Block emails from configured outgoing mail

Jira will has a default outgoing email address configured. If you enable this setting, the mail handler will not parse incoming mail from this address.

Allowed Domains

This setting allows you to control which sender domains will be processed. For example, if you want to ignore any emails from outside example.com, then you could place example.com into the field and emails from gmail.com would be ignored. If you need to place multiple domains, then you can use a comma to separate them.

Catch Email Address

If you enter an email address here, when the Mail Handler parses the To field of an email, if they two don’t match, the email is ignored.

You can only place one email address in this field.

Bulk

This tells the Mail Handler how to handle emails that are generally referred to ask Bulk. In particular, we’re looking at the following two headers:

Precedence: bulk Auto-Submitted: auto-generated

  • Ignore the email and do nothing - The email remains in the mail box and the Mail Handler continues to try and parse it every time. If you’re not manually checking this mailbox and cleaning it up periodically, this may lead to slowdown and performance issues.

  • Accept the email for processing - The email is processed and a new Issue or Comment is created.

  • Delete the email permenantly - Deletes the email from the mail box. Only use this option if you are confident important email won’t get flagged as bulk.

On error?

When we run into a Jira related issue then we can send an email notifying the Project Lead or the original Email Sender that something went wrong.

  • Send email to the project lead

  • Send email to the e-mail sender

  • Disabled