Versions Compared

Old Version 5

changes.mady.by.user Giles Gaskell

Saved on

compared with

New Version 6

changes.mady.by.user Giles Gaskell

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

JIRA can be configured to automatically create issues or comments based on incoming email messages. 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 automatically be attached to the issue (with appropriate configuration).

On this page:

Table of Contents
minlevel2

Mail Service Configuration

...

  1. Log in as a user with the 'JIRA Administrators' global permission.
  2. 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.
  3. On the panel on the left, under the title 'Global Settings', click the link labelled 'Mail Servers'.
  4. Click the 'Configure new POP / IMAP mail server' link. This will bring up the 'Add POP / IMAP Mail Server' page (see Configuring JIRA to Receive POP or IMAP Mail).
  5. Fill in as follows:
    • 'Name:' enter a short descriptive name, possibly just the email address that will be collected by this service
    • 'Description:' enter a short phrase that describes this service, probably 'Email Issue Creation/Comments for <Project>'.
    • 'Host Name:' enter the name of your POP or IMAP mail server
    • 'Username' and 'Password:' use the email account details as created in 'Step One' above.
      (info) Note that the use of SSL is specified later in the service, not here in the Mail Server.
      (info) 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.
  6. Click the 'Add' button.
  7. This will bring you back to the 'Mail Servers' page, where you should see a new POP or IMAP server listed towards the end of the page. You can edit and delete this server here.
  8. On the panel on the left, under the title 'System', click the link labelled 'Services'.
  9. 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', which cannot be deleted. Additionally, if you have enabled the option to automatically backup JIRA's data, you will also see the 'Backup Service' listed here too.
  10. Fill in the 'Add Service' form as follows:
    • 'Name' — enter a descriptive name, eg "Create Issue/Comment Service for <Project>".
    • 'Class' — select the appropriate option presented in the drop down list, or enter com.atlassian.jira.service.services.pop.PopService,
    • 'Delay' — this is best left as 1 minute.
  11. Click the 'Add Service' button.
  12. This will bring up the 'Edit Service' screen to configure the service.

    • 'Handler' — select "Create Or Comment Handler" from the drop down box. In the 'Handler parameters' field, set Handler parameters to something like:

      Code Block
      project=JRA, issuetype=1, catchemail=foo@example-co.com, createusers=true, bulk=forward

      Further details on the handler parameters are available below.
      (info) 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.

    • Forward Email — this 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.
  13. Click the 'Update' button and the service will be in effect.

...

  • 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: \, /, ", %, :, $, ?, *, <, |, >.
    • If the incoming email is set to a high priority, the corresponding issue will be created with a higher priority than the default priority that is set in your JIRA system.
  • 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 attachmentshave been enabled in JIRA)

      Info

      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.

...

  • createusers — if createusers is set to true, people who don't currently have an account in JIRA will have it created for them. 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" e-mail address is appended to the issue description field when the issue is created, so you can identify the sender.
    (info) Please make sure the specified user has permission to create issues or comments in the project in question. See Managing Project Permissions.
  • 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 the To or Cc field of an email contains the address of a user already present in JIRA, then by default JIRA will assign the issue created from the email to that user. JIRA will attempt to assign the issue to a user from the To field first, then the Cc field, if it cannot find a match in the To field. If you do not wish JIRA to automatically assign issues in this way, then 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 "Precedence: bulk" header or an "Auto-Submitted" header that is not set to "no". 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 permanentlyIt 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 email address specified in this field. Upon specifying an address here, all other email addresses are ignored. This is useful if you have multiple aliases for the same email Inbox, eg. foo-support@example-co.com and bar-support@example-co.com aliases for support@example-co.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.
  • stripquotes --- This option enables the use of the  NonQuotedCommentHandler to strip previous messages from replies.

...

  • Ensure mail is sent to a backup folder, so there is a record of what JIRA processed.

  • If the POP box contains email replies to JIRA notifications, set up rules filtering out email auto-replies and bounces.
    If you do not do this, there is a strong possibility of mail loops between JIRA and autoresponders like vacation scripts. JIRA sets a 'Precedence:bulk' header (unless you've disabled this) and an 'Auto-Submitted' header on outgoing email, but some autoresponders ignore it.
    There is no bulletproof way of detecting whether an email is a bounce or autoreply. The following rules (in procmail format) will detect most autoreplies:

    Code Block
    
^From:.*mailer-daemon@
^Auto-Submitted:.auto-
^Content-Type:\ multipart/report;\ report-type=delivery-status
^Subject:\ Delivery\ Status\ Notification
^Subject:\ Undeliverable
^Subject: Returned Mail:
^From:\ System\ Administrator
^Precedence:\ auto_reply
^Subject:.*autoreply
^Subject:.*Account\ signup

    Even with these rules, you may encounter autoreplies with nothing in the headers to distinguish it from a regular mail, In these cases you will just need to manually update the filters to exclude that sender.

  • Set up a filter to catch email with huge attachments. JIRA uses the standard JavaMail library to parse email, and it quickly runs out of memory on large attachments (eg. > 50Mb given 512Mb heap). As the unhandled mail isn't deleted, it will be reprocessed (causing another OutOfMemoryError) each time the mail service runs.
    In practice this problem is rarely seen, because most mail servers are configured to not accept email with huge attachments. Unless you're sure yours won't pass a huge attachment on to JIRA, it is best to configure a filter to prevent JIRA encountering any huge attachments.
  • Set up spam filtering rules, so JIRA is not having to process (and possibly create issues from) spam.

...

  • If JIRA doesn't appear to be creating sending emails or creating issues and comments from email, your JIRA instance could be experiencing OutOfMemory errors. Please check your log files for OutOfMemory errors. If there are OutOfMemory errors, please restart JIRA and investigate the errors.
  • 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.If you receive email with non-ASCII attachment names, particularly from Thunderbird users, you will need to configure JavaMail to support RFC 2231-encoded attachments. See JRA-12525 for details.
  • If replies by email of JIRA's notifications list JIRA's SMTP server rather than the configured handler POP account (ie, in Outlooks' 'Reply-to' functionality), the project needs to be configured to add a 'reply-to' header in outgoing notifications. This can be configured in the project view for that particular project in JIRA's Administration.
  • If HTML/Rich Text formatting is not being process correctly by JIRA, this is an expected behavior. The email comment handler was designed to do plain text conversion.

...