|
|
 |
Creating Issues and Comments from Email
| 
PDF |
JIRA can be configured to automatically create issues or comments based on incoming emails. This is especially useful in a
helpdesk or support scenario, where users send support queries via email, which you wish to track with JIRA.
Subsequent emails about the issue, for example responses to Email Notifications,
can be automatically recorded as comments. Additionally, any attachments in the emails can be automatically attached
to the issue (with appropriate configuration).
To set up issue and comment creation via email, you will need to create a mail account on your server (usually one mail
account for each project). For example, for the 'ABC' project, you might establish an account abc-issues@yourcompany.com.
This mail box should be accessible via POP, IMAP, or on the local filesystem. JIRA will periodically scan this
mail box, and appropriately create issues or comments for any emails it finds, and — optionally — create
new user accounts for senders not previously seen (note that this is not possible if you are using
External User Management).
Once you have established a mail account, here is how to configure JIRA to periodically scan it (POP access assumed):
- Log in as a user with the 'JIRA Administrators' global permission.
-
Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the
Administration box on the dashboard:
 
-
On the panel on the left, under the title "Global Settings", click on the link labelled "Mail Servers".
-
Click on the "Configure new POP mail server" link.
-
This will bring up the "Add POP Mail Server" page.
Fill in as follows:
-
Name: put a short descriptive name, possibly just the email address that will be collected by this
service
-
Description: put a short phrase that describes this service, probably 'Email Issue Creation/Comments for <Project>'.
-
Hostname: put the name of your POP server
-
Username and Password use the email account details as created in step 1.
Note that the use of SSL is specified later in the service, not here in the Mail Server.
If you need to set a non-standard port, this will need to be done by setting a
-Dmail.pop3.port=<port> property (instead of pop3 you can specify
pop3s, imap or imaps). See JRA-11037 for more on this.
-
This should bring you back to the Email Servers page, where you should see a new POP server listed. You can edit
and delete this server here.
-
On the panel on the left, under the title "System", click on the link labelled "Services".
-
This will bring up the "Services" page. It lists the current services running on this system. On a vanilla
system there should be one service running - Mail Queue Service. You cannot delete the Mail Queue Service.
Additionally, if you have enabled the option to automatically backup JIRA's data, you will also see the Backup
Service listed here too.
-
Fill in the "Add Service" form as follows:
For Name enter a descriptive name, eg "Create Issue/Comment Service for <Project>".
For Class, select the appropriate option presented in the drop down list, or enter
com.atlassian.jira.service.services.pop.PopService, and the Delay is best
left as 1 minute. Click Add Service.
-
This will bring up the "Edit Service" screen to configure the service.
For Handler, select "Create Or Comment Handler" from the drop down box. Set Handler parameters to
something like:
project=JRA, issuetype=1, createusers=true, bulk=forward
Further details on the handler parameters are available below.
If you choose to connect over SSL, you will need to import and verify the server's SSL key before JIRA will
be able to connect. See Connecting to SSL Services for more information.
The Forward Email parameter specifies an email address to which error notifications and
(optionally) unhandled emails can be forwarded (see "bulk" parameter below). Any unhandled mails or failures
encountered in this process are logged and forwarded in an email to this address.
Click the "update" button and the service will be in effect.
Issue/Comment Creation
JIRA examines the email subject and the in-reply-to message for an existing issue reference
to determine whether a new issue or comment should be created. A new issue is created if an existing issue reference
is not found - otherwise, a comment is added to the issue referenced in the email. The email to foo@atlassian.com will be processed as follows:
- Issue Creation:
- The subject of the email will become the issue summary.
- The body of the email will be the issue description.
- A bug (since issue type has been set to 1 in this example) will now be created for project "JRA" with the above
information.
- Any attachments to the email will become attachments to the issue (assuming attachments have been enabled in JIRA). Note that, to ensure compatibility with various
operating systems, any of the following characters in the filename will be replaced with an underscore
character: \, /, ", %, :, $, ?, *, <, |, >.
- Comment Creation:
- The body of the email will become a comment on the issue
- Any attachments to the email will become attachments to the issue (assuming attachments have been enabled in JIRA)
Note
The Subject of the email becomes the issue summary. As all issues require a summary, each
email intended for issue creation should include a Subject.
Handler Parameters
project parameter is the project key.
These are the numbers associated with the default issue types:
-
Bug: issuetype=1
-
New Feature: issuetype=2
-
Task: issuetype=3
-
Improvement: issuetype=4
-
Sub-task: issuetype=5
Besides project and issuetype, the following parameters are allowed:
-
createusers
- If createusers is set to true, people who don't currently have an account in JIRA will
have it created for them. In JIRA Enterprise, this allows the creator to be notified of subsequent updates
to the issue, by configuring the notification scheme to notify the 'Reporter' of updates.
-
reporterusername
- This sets which user will be the "reporter" of created issues, for emails whose sender does not
match that of an existing user. Normally JIRA will ignore emails from addresses not matching an existing
user. For instance, to allow anonymous users to create issues via email, you can create an
anonymous user or dummy account on JIRA and set the reporterusername to point to this
account. When the "reporterusername" parameter is specified, the "from" address of the email is added at the
end of the comment of the issue, so you can identify the sender.
-
notifyusers
- This parameter is only used if createusers is set to true. If notifyusers
is set to false they will not receive a notification that their account has been created via email. The
default value is true to preserve the behaviour before this parameter was added.
-
ccassignee
- If an email has a Cc address listing a user already present in JIRA, by default JIRA will
assign the issue created from the email to that user. If you do not want this behaviour,
set ccassignee to false.
-
bulk
- This parameter determines how to handle "bulk" emails (those sent by an automated service, notably JIRA
itself), indicated by a "Predecence: bulk" header. Possible values are:
-
ignore - Ignore the email and do nothing
-
forward - Forward the email to the address set in the "Forward Email" text field
-
delete - Delete the email permanently
It is generally a good idea to set bulk=forward and set a Forward Email address, to
prevent mail loops between JIRA and another automated service (eg. another JIRA installation).
-
catchemail
- This causes JIRA to only process emails sent to the specified email address. All other
emails are ignored. This is useful if you have multiple aliases for the same email Inbox, eg.
foo-support@example.com and bar-support@example.com aliases for
support@example.com, and you want one email service each, eg. to create issues in FOO
and BAR projects respectively. Please note that this parameter is rarely useful,
and should not be confused with the more common reporterusername.
You can only specify one catch email address and one issue type per listener.
Other Handlers
For more information on other handlers that are shipped with JIRA please refer to this document.
Troubleshooting
A useful tip for debugging mail-related problems in JIRA is to set the
-Dmail.debug=true property on startup. This will cause protocol-level details of JIRA's email
interactions to be logged. Additionally, turning up JIRA's log level will show
when the service is running and how mails are processed.
If you find some incoming emails simply disappear, check that you haven't accidentally started a second
copy of JIRA (eg. in a staging environment) which is downloading and deleting mails. See the Restoring Data page for flags you should set to prevent mail being
processed.
| |
|
