CERT® JIRA Attachment Mail Handler (EAH)

The CERT® JIRA Attachment mail handler creates a new JIRA issue from incoming emails. If the incoming emails is just text/plain, its data is used to create the issue. If the incoming email is multi-part and there is a single RFC-822 attachment, it is interrogated and used to create a new JIRA issue. This allows a user to "forward as an attachment" and have the forwarded email be the input for a new JIRA issue.

The handler supports both S/MIME and PGP encryption. The BouncyCastle libary is being used to perform the decryption.

This handler was coded and tested using JIRA version 4.4.5, however preliminary testing has successfully been conducted in JIRA 4.x.


pkcs7-signature files will not be attached to the newly created JIRA issue.

No Attachments

A single JIRA issue will be created based on the email data.

Email with Single Attachment

If the single attachment is RFC-822 compliant, the main email body and the attachment's body are combined to form the description for a single JIRA issue. By default the attachment's information is used to build the issue data (reporter,assignee,summary). If the attachment's From: field is not a valid JIRA user, the forwarder's From: will be used. This behavior can be controlled by both a Service Parameter and a X-Header value.

If the single attachment is encrypted, it will be decrypted. If it cannot be decrypted, it will be attached to the JIRA issue as is.

Email with Multiple Attachments

The main email's body will become the description for the new JIRA issue. Each email attachment will be attached to the newly created JIRA issue. If the attachment can be decrypted, the decrypted text will be attached to the JIRA issue. If an attachment cannot be decrypted, it will be attached to the JIRA issue as is.


Copy all of the JARs from this distribution's lib to directory to JIRA's lib directory (usually /opt/tomcat/webapps/jira/WEB-INF/lib)


Most configuration options can be set by either a service parameter or an X-Header on the email. For all boolean values if they are not specified, their value will be false. If a value is specified both as a configuration parameter and as an X-Header, the X-Header value will be used.

All parameters that accept a username also accept an email address.

Service ParameterRequiredX-HeaderAllowed ValuesComments
addccusersNoX-AddCCUsersfalse,trueBoolean value. If true, all valid users, identified from the CC email header,will be added as watchers to the issue.
defaultassigneeNoX-DefaultAssigneeJIRA username/email addressIf specified, all issues will be assigned to the specified default assignnee.
issuetypeYesX-IssueTypeValid issue type integer identifier1=Bug, 2=New Feature, 3=Task, 4=Improvement
priorityNoX-Priority1,2,3,4,51=Blocker, 2=Critical, 3=Major, 4=Minor, 5=Trivial  Default == 3
projectYesNoneProject IDThe value will automatically be converted to all uppercase
recipientassigneeNoX-RecipientAssigneefalse,trueBoolean value. If true, the first found user (in To & CC) will be the assignee for new issue.
reporterassigneeNoX-ReporterAssigneefalse,trueBoolean value. If true, the reporter will be the assignee for the newly created issue
reporteroverrideNoX-ReporterOverrideJIRA username/email addressIf specified, the reporter will always be the specified value. If specified with a valid JIRA user (or email address), no other reporter determination will occur.
reporteruserNoX-ReporterUserJIRA username/email addressIf specified, the specified user will be the reporter if the reporter cannot be determined from the From: header. This parameter serves the same purpose as reporterusename for the http://www.atlassian.com/software/jira/docs/v3.13/issue_creation_email.html}Create Issues and Comments Handler. It is a fallback value if no other way of calculating the reporter results in a valid JIRA user.
supressCreatedNoX-SuppressCreatedfalse,trueBoolean value. If true, the "Create via email" description text will be suppressed

reporteruser is the only handler parameter that EAH shares with Create Issues and Comments Handler

Update JIRA Configuration Files

  • Add the following lines to fileservice.xml (or popservice.xml or imapservice.xml) +-- value keyorg.cert.cc.jira.email.handler.AttachmentMailHandler/key valueCERT Attachment Handler/value /value +--

    The relevant section should start with:


    And include the other Email Handlers. All 3 XML files are located in directories under

  • Log into JIRA (an account with admin privileges)
  • Select "Administration"
  • Select "Services"
  • In the "Add Services" input area
    • Enter a Name
    • Click on "Built In Services"
    • Click on one of the following:
      • "Crease issues from POP",
      • "Create issues from IMAP",
      • "Create issues from local files." These correspond to the XML file changed above.
    • Click Add Service
  • In the "Edit Service" form:
    • In the Handler drop-down select "CERT Attachment Handler"
    • Any parameters (see above) in the "Handler parameters" field.
    • Click Update

Custom Field Processing

EAH can set any number of custom fields with data. The data can either be static or extracted via regular expression from the input email message.

The data is read in the from the Application.properties file (/etc/certops-jira/eah/Application.properties). Each custom field processing instruction consists of three (one is optional) fields.

Field NameRequiredDescription
nameyesThe custom field name. This must be exact
valueYesStatic data or regular expression for the value of the custom field
inputNoIf specified, it instructs EAH what message field to use against the regular expression. Legal values are: SUBJECT, BODY

Each custom field description set is prefixed with custom.field.N., where N is a digit. There cannot be a gap in the sequence. EAH will keep loading custom field descriptions until custom.field.N.name returns null.

Example Application.properties

    custom.field.1.name=Contact Method



The regular expression must contain a capturing parenthesis. EAH will use the capture data as the value for the custom field. In the example above, the InternalTracking# value will be the text captured by ([-0-9]+).

If any errors happen with the custom fields, a warning is logged but the issue will still be created.


The CERT® Attachment Mail Hander configures log4j by:

  1. If eah-log4j.properties is anywhere in the classpath, it is used. Usually /opt/tomcat/webapps/jira/WEB-INF/classes
  2. If no eah-log4j.properties is found, /etc/eah/log4j.properties is checked. If this file exists, it is used.
  3. No logging is done.

Determine Issue Assignee Algorithm

  1. If reporterassignee is set to 1, the assignee is the reporter
  2. if recipientassignee is set to 1, the To: followed by the CC recipients is scanned looking for a valid JIRA user. The first one, that is found, becomes the assignee.
  3. The default assignee --usually the project lead, becomes the assignee.
  4. Assignee is set


  • Attachment Mail Handler does not support catchemail. All incoming emails will be processed.
  • Attachment Mail Handler will not create any new users.
  • Attachment Mail Handler always search To and the CC headers looking for a valid user. ccassignee is not currently supported.
  • Most, all except project, Attachment Mail Handler parameters can be overridden with X-headers.