Directives
- Fernando Boucquez (PPL) (Deactivated)
- Euan Wynne (Deactivated)
- Andy Brook [Plugin People]
Summary
Directives are commands given to JEMH Cloud that determine how Jira issue fields (and custom fields) are set. Their primary use is to allow fields to be populated with values via email. The location and format of the data used for directives depends on the Field Processor selected to parse incoming emails.
Field processors by directive location in email
Subject | Body | Headers |
|---|---|---|
#Prefix Field Processor |
|
|
Example directive formats
Field Processor | Example | Notes |
|---|---|---|
X-JEMH Header Field Processor |
X-JEMH-issueKey: JDP-19
X-JEMH-description: Hello, World!
|
|
#Prefix Field Processor |
#description="Hello, World!"
[#issueKey=JDP-19]
|
|
@Prefix Field Processor |
@description=Hello, World!
@issueKey=JDP-19
This line is the start of the email text content. Note the blank separating line above.
|
|
Colon Suffix Field Processor |
|
|
Nagios Field Processor |
| |
Regexp Field Processor |
|
Enabling directive use with field processors
Be default directives found within inbound mail won't get processed by JEMHC. You need to determine when Directives should be processed:
Profile > Mapping > Field Processors > General Configuration > Apply field processors (Off | On Create | On Comment | On Create/Comment)
Selecting field processors
Each type of field processor must be enabled within the 'Field Processors' view of your desired project mapping. Configurations applied to your default project mapping will also apply to any other project mapping contained within the same profile, unless they themselves set things differently.
All enabled Field Processors go through an election to determine which one should process the mail. They aren’t additive, the Field Processor with the most directives found will be used.
Supported Directives
Re-implementing support for Directives in JEMHC will be an ongoing activity. This page reflects the status of support for modifying issues through Directives, processed by Field Processors. Dependent on priority level i.e. Mapping Rule level directives overrides Project Mapping level directives and Project Mapping level directives overrides Default Project Mapping inheritance level directives.
Directive | On Create | On Comment | Notes |
|---|---|---|---|
summary | Replaces existing summary | ||
reporter | Replaces both from address and profile's default reporter | ||
emailSenderAsUser | Not supported yet | Not supported yet | |
assignee | Replaces profile's default, If the assignee is not assignable, the message will be rejected | ||
issueType | Issue type is specially important because the metadata depends on it. If not valid for the project, the message will be rejected | ||
issueKey | N/A, JEMH will comment the issue if it exists | Yes, changes issue to be commented/updated taking precedence over the issue key in subject, mime header threading and the associated issue to the mime message id. Equality condition and custom JQL are supported (1.0.86+), JEMHC resolves the first not resolved issue that matches the criteria. Examples:
| |
parentIssueKey | Possible UC could be replying to a subtask issue with | ||
labels | CSV splitting the field processor value, not taking in consideration any escaping Label values are added with the labels set in issue parameters in the Profile. | ||
priority | |||
description | Replaces the post processed body of the email | ||
comment | Create: Adds the directive's value as a comment after the issue has been created. Comment: Uses as body of the comment replacing the body of the post processed email | ||
components | Yes - Set | Yes - Update | Not escaped CSV. If one of components in the list is invalid, it will be ignored (with reporting) |
project | Yes - It changes where the issue will be created ignoring the project key in profile | Yes but it just used as validation. Comment fails if the resolved issue key doesn't belongs to the project | Project is also important as metadata depends on it. Validation in UI can fail during processing. e.g: some custom fields or issue type is not available in the directive's project. When using this directive we recommend also using the issueType directive to ensure that a valid issueType is used during issue creation. |
dueDate | |||
requestType | Not possible to change | Service Desk’s request type. Name or id can be provided. For example:
| |
dueDateFormat | Replaces profile's default due date | ||
Epic Label |
| It set the epic label of the create or updated issue only if the issue is of type Epic
| |
Epic Link | Value can be either the key or the label of the target epic.
| ||
Sprint |
| it assigns the issue to a sprint.
| |
watchers |
|
|
|
viewable | Not supported yet | Not supported yet | |
ccusers | Not supported yet | Not supported yet | |
workEstimate | Not supported yet | Not supported yet | |
environment | Yes - Set | ||
linkto | Not supported yet | Not supported yet | |
affectsVersions | Not escaped CSV. If one of versions in the list is invalid, it will be ignored (with reporting). | ||
fixVersions | Not escaped CSV. If one of versions in the list is invalid, it will be ignored (with reporting). | ||
vote | Not supported yet | Not supported yet | |
logWorkDone | Not supported yet | Not supported yet | |
securityLevel | - Set | - Update | The field name is 'security' |
attachments | Not supported yet | Not supported yet | Attachment is not a field |
stripComments | Not supported yet | Not supported yet | |
Worklog directives | Not supported yet | Not supported yet | All the directives related to work-log |
notifyOnEdit | Not supported yet | Not supported yet | |
workflow | Resolution defaults to Fixed. Only One transition permitted (so far). Basic version. The transition is applied after everything else: update issue, comment issue, upload attachments
| ||
workflow.resolution | Resolution is set if it's allowed in the transition, e.g.
| ||
workflow.params | A workflow field is set if it is allowed in the transition or it is allowed in the issue after the transition has been applied.
| ||
issueTemplate | Not supported yet | Not supported yet | |
custom fields | Set overriding default custom field values but not the custom fields used for email only users | Update (including custom fields used for email only users) | |
internalComment | if there is a @comment directive | If the issue is a Jira Service Management request, Users may find it useful to create |
Custom Fields validated
The following built in custom field types have been validated. Some are automatically set.
You can use either field name (case insensitive) or field id (like customfield_10001) as directive key. Multiple values are comma separated.
Examples are using colon notation. At notation (@key=value) and subject notation (#key="value") are also possible
Type | Example Value |
|---|---|
Checkboxes | custom checkboxes: option 1, Option 2 |
Custom Google Map Field | Not supported yet |
Customer Request Type | Supported for create operation. JIRA raises an unexpected runtime exception on issue update. Example:
Read more about the value format in this wiki page. |
Organizations | Allowed values are organization names or id (number). One or more organizations can be entered using comma separated values.
|
Date of First Response | Not supported yet |
Date Picker |
(Using default format of or
(Second directive defines the format, it's the field name following 'Format') |
Date Time Picker |
(Using default format of or
(Second directive defines the format, it's the field name following 'Format') |
Global Rank | Not supported yet |
Group Picker (multiple groups) | Not supported yet |
Group Picker (single group) | Not supported yet |
Hidden Job Switch | Not supported yet |
JIRA Agile Released Version History | Not supported yet |
Job Checkbox | Not supported yet |
Labels |
|
Multi Remote Object Link | Not supported yet |
Number Field |
|
Project Picker (single project) |
|
Radio Buttons |
|
Remote ObjectLink | Not supported yet |
Remote System Reference | Not supported yet |
Select List (cascading) |
|
Select List (multiple choice) |
|
Select List (single choice) |
|
Tempo Account |
|
Text Field (multi-line) | |
Text Field (read only) |
|
Text Field (single line) |
|
Time In Status | Not supported yet |
URL Field |
|
User Picker (multiple users) |
|
User Picker (single user) |
|
UUID Field | Not supported yet |
Version Picker (multiple versions) |
|
Version Picker (single version) |
|