...
Info |
---|
Directives are flexible
|
Issue fields
Project
Directive key | Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) |
---|---|---|
|
|
|
Reporter
Allows overriding the reporter that would be determined via profile configuration for the email. The value must identify an actual user by their username, and not their email address.
Directive key | Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) |
---|---|---|
|
|
|
Assignee
Directive key | Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) |
---|---|---|
|
|
|
Issue Type
The value can either be a name or ID number.
Directive key | Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) |
---|---|---|
|
|
|
Priority
The value can either be a name or ID number.
Directive key | Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) |
---|---|---|
|
|
|
Components
The value can either be a name or ID number.
Directive key | Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) |
---|---|---|
|
|
|
Watchers
Directive key | Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) |
---|---|---|
|
|
|
Due date
Note |
---|
Note that from JEMH 2.5.1 date values supplied by email directives are locale sensitive. This means that for example, a Jira user who's profile is set to Spanish should send date values such as |
Directive key | Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) |
---|---|---|
|
|
|
The due date value format must match one of the following:
...
Used in combination with the due date directive. This is only required if using a format other than the Jira system format (see due date section for more information).
Directive key | Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) |
---|---|---|
|
|
|
Original Estimate
The original estimate for work can only be set during issue creation. The directive value must follow the standard Jira duration mark-up.
Directive key | Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) |
---|---|---|
|
|
|
Affects Versions
Directive key | Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) |
---|---|---|
|
|
|
Votes
The ability to vote on an issue can be done through an email Directive (as long as the related issue is somehow identified):
Directive key | Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) |
---|---|---|
|
|
|
Security level
Directive key | Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) |
---|---|---|
|
|
|
Custom fields
Custom fields using any the standard custom field types can be set via email. Non-standard custom field types may also be supported, if they can take String values of a known format.
...
Lists and arrays of values are supported as Comma Separated Values (no additional white-space)
Cascade Selects are supported through the format Your Custom Field Name=First Selection,Second Selection
Directive key | Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) |
---|---|---|
Name or ID of field e.g. |
|
|
Note |
---|
Note that from JEMH 2.5.1 date values supplied by email directives are locale sensitive. This means that for example, a Jira user who's profile is set to Spanish should send date values such as Prior to 2.5.1, date values should be sent using the system default locale. |
...
Used to comment/update pre-existing issues. This overrides any issue key found in the subject. Additionally, the target issue can be identified through a simple custom field query:
Example | Description |
---|---|
| The issue ABC-123 is used for operations within the email and for commenting. If the issue is not found, the email will be rejected with hintOgram messages |
| When the directive value is found to not be an issue key, its treated as a JQL query. The first matching issue with the given Custom Field (e.g. 'Some Custom Field') with a specific value would be used as the target. |
Sub-tasks
Sub-tasks can be created by telling JEMH what the parent issue is. This parent issue can be specified with an issue key or a simple custom field query.
Example | Description |
---|---|
| The issue ABC-123 is used for operations within the email and for commenting. If the issue is not found, the email will be rejected with hintOgram messages |
| For example, when the value of the parentIssueKey does not resolve to an issue, its treated as a query, such that the fist matching issue with the given Custom Field (e.g. 'Some Custom Field') with a specific value would be used as the target. |
Currently only the 'Sub-task' issue type is supported (it must exist). HintOgram notifications will be issued if the 'Sub-task' issue type doesn't exist or if Jira has not got 'sub-tasks' enabled.
...
Note |
---|
Using this directive in an email subject may cause conflicts with JEMH’s subject issue key association functionality. Therefore, to be able to use this directive in the subject, the Regexp (in JEMH > Profile > Email > Pre-processing > Subject IssueKey (comment) Regexps) should to be changed to the following: |
Directive key | Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) |
---|---|---|
|
|
|
Workflow transitions
Directive key | Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) |
---|---|---|
|
|
|
Some workflow transitions need additional parameters. For example, when resolving an issue a resolution is often required. Parameters can be provided by prefixing the parameter directive with workflow.
(see resolution example below).
Directive key | Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) |
---|---|---|
|
|
|
If parameters are required but no value can be determined, the transition will fail.
...
For inbound emails that contain worklog directives, the email body is taken as the worklog comment. It will not be added to the issue.
If no
wl.startDate
directive is provided the date at which the email is processed will be usedTo differentiate worklog directives from any other directives/fields, they are all prefixed with
wl.
If there is a default set for worklog comment visibility, users can override with
wl.viewable.role
orwl.viewable.role
directives. If a public worklog entry is wanted, the default can be overridden withwl.viewable=true.
Defaults are checked for in the following order, first non null value is used
Role
Group
Date format is the system default
Logging time spent
Directive key | Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) |
---|---|---|
|
|
|
Logging time spent and updating remaining estimate
Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) | ||
---|---|---|---|
|
|
Logging time spent and overriding visibility
Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) | ||
---|---|---|---|
|
|
Logging time spent, updating estimate and restricting visibility to a role
Example using At Prefix Field Processor (in email body) | Example using Subject Field Processor (in subject) | ||
---|---|---|---|
|
|
Column | ||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Special ProcessingEvent TypeAs inbound mail can contain a variety of fields, content could trigger any of the stock event templates (e.g. issuecommented.vm). By default the issueupdated.vm template is used. By enabling the following option, the event type will be automatically selected as appropriate. The rule of thumb is that if a single type of information is provided (e.g. a comment, a worklog), that event would be used, combined input will result in a standard IssueUpdated event being used.
Sender Email AddressThe sender email address can be redirected into a nominated Custom Field:
CC:
There are several Options for CC: handling, if enabled, can be:
These options are not mutually exclusive, e.g. ccHandling=toWatcher,toCustomField AttachmentsIf any attachments are present in either initial creation or comments, they will be added to the issue. IssueTypeThe issueType can be determined in several ways:
Field Processors
There are many known keys for emails which are covered on the main add-on page. JEMH has been written with extension and customization in mind. The existing Configuration includes the following Options:
Initial issue creation notifications for allIf the Option notifyUsersOnIssueCreation is set, (values are none,nonjira,jira,all), it is possible to trigger notifications of issue creation, separate to the Jira notification scheme. The purpose of this is to enable users who send email into Jira (when auto-creation is not on, or they don't qualify) to get some kind of notification that the issue got created. This currently only applies to the original email sender. Customisation of from: address for JEMH sourced notificationsThe following options, if either is specified, will override whatever Jira defaults have been setup on the default mail server:
Stripping QuotesThe Option stripQuotes enables inbound emails to be automatically stripped of indented content indicative of the reply-to-jira-mail scenario. This stops ever longer duplicate content additions.
Notify users without eating Jira license seatsA problem with the Jira license model is that sometimes you want to enable customers to send emails to Jira, to create tickets, those users don't need to be able to login to Jira but do need to receive related issue update notifications. JEMH can do this, if you set it up as follows: Gutting the example configuration file does more than just remove fields you don’t care about (right now), it removes the related documentation. My advice is to keep the example, just comment out what you don't need. Required configuration fields
Issue CreationIn order to create issues, that user must have 'Jira User' global privilege, normally this is given to jira-users. In order to create issues you must provide a userid that has such membership, and privileges in the project (perhaps identified through the defaultProject configuration option:
This now enables issues to be created by anyone, but is not attributed to them directly. Creating users without taking Jira seatsIn order to support the notification of users, the approach is to create users without giving them 'Jira User' global privilege. Given that you must provide access to users without knowing their ID, you must also nominate a group, which is likely given 'User' privilege in your project (specifically, the Browse Project permission). The exact nature of the userId is configurable and is extendable, but is not required:
Overall functionWhen the issue has been created, the issue creator is set to the defaultReporterUsername, the remote email user that has been created, is added as a watcher, and will now receive subsequent notifications.
Blocklisting andWhitelistingAllowlistingThere are several reasons you may want to block certain emails, for example:
JEMH provides pretty comprehensive filtering behaviour to nail the annoying emails that you cant get filtered some other way: WhitelistingAllowlisting
BlacklistingBlocklisting
Greylisting
Customizing the Hint/Reject EmailsThe Hints generated during processing are rendered through two sets of template files, HTML and plain text. If an inbound email from: address is found to relate to a Jira user, that users email format preferences are used, plain text otherwise. Hint template filesThe locations of the templates are in the JAR under /templates/email/jemh/html and /templates/email/jemh/text. To customize, just take copies and add to the WEB-INF/classes/templates tree. Hint ID'sSome hints have numeric ID's associate with them to allow custom .vm level content provision over the perhaps verbose techno-babble message. These can be added on request. Trouble ShootingEmail ErrorsFields on long lines are not found or truncated in JiraThis can happen when custom fields or description fields contain more than trivial information, e.g. > ~80 characters:
Problems with WYSIWYG Rendering of description field.See JEMH-55. Workaround for now is use wiki-renderer. Problems with email subject truncation using # character?This is because the SubjectBasedFieldProcessor is trying to process those values. To stop that you can either change the emailFieldProcessorPriorityLowerLimit and emailFieldProcessorPriorityUpperLimit to select the range (only) of processors to employ according to the table below:
If that isn't good enough (or if you just want to reduce 'noise' of handlers that aren't ever going to be used) it's also possible to open the Jar an remove the appropriate class with no side-effects.
Related Articles
|
...