Summary
Directives allow issue fields (and custom fields) to be populated with values indirectly via email. Directives can be in many different formats. Depending on the format, there will be a specific Field Processor that can be used to parse the directives. For example, supplied directives in the format "@directive=value" are parsed by the @Prefix Field Processor.
Enabling Directives
Be default directives found within inbound mail won't get processed by JEMHC. 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.
Directive Formats
JEMHC supports several formats of data in which directives can be supplied, spread across mail subject, body, and headers as follows.
| Mail Subject | Mail Body | Mail Headers |
|---|---|---|
| #Prefix Field Processor |
|
|
Examples
| Field Processor | Example | Notes |
|---|---|---|
| Mail Header | ||
| X-JEMH Header Field Processor | X-JEMH-issueKey: JDP-19 X-JEMH-description: Hello, World! | Included in the raw email. |
| Mail Subject | ||
#Prefix Field Processor | #description="Hello, World!" [#issueKey=JDP-19] | Strings wrapped with quotes. |
| Mail Body | ||
@Prefix Field Processor (Preferred) | @description=Hello, World! @issueKey=JDP-19 | Keys prefixed with "@". Must go at top of body. ONE Newline between directive lines otherwise value is considered multi-line. Multi-line fields will go until end of body, or until another directive is found. ONE Empty line between between Directives and Body |
Colon Suffix Field Processor | description:Hello, World! issueKey:JDP-19 | Keys suffixed with ":". Newline mandatory. Must go at top of body. Multi-line fields will go until end of body, or until another directive is found. |
| Nagios Field Processor | Nagios Field Processor Guide | |
Regexp Field Processor | Regexp Field Processor Guide | |
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.
| 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 | |
| See https://answers.atlassian.com/questions/9374899/can-i-change-sub-task-parent-using-rest |
| labels | | | csv splitting the field processor value, not taking in consideration any escaping Label values are 'set' not 'added'. Currently overrides the 'profile' labels (should we merge?) |
| 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 |
| dueDate | | | |
| 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 Label=The Epic Label |
| Epic Link | |
| Value can be either the key or the label of the target epic. @Epic Link=SCRUM-123 @Epic Link=The Epic Label |
| Sprint | |  | it assigns the issue to a sprint. @Sprint=6 (Sprint with id 6) @Sprint=Board Name:Sprint Name @Sprint=Board Name (Active sprint in board 'Board Name') |
| watchers | | | @watchers=someJiraUserName, someJiraUserEmail@myCompany.com |
| 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). 'affectsVersions' is actually the 'version' field labeled 'Affected Versions' in UI. |
| 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' |
| Attachment is not a field | |||
| Worklog directives | Not supported yet | Not supported yet | All the directives related to worklog |
| 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:Start Progress @workflow=Close Issue |
| workflow.resolution | | | Resolution is set if it's allowed in the transition, e.g. workflow:Close Issue workflow.resolution=Duplicate |
| workflow.params | | | A worklow field is set if it is allowed in the transition or it is allowed in the issue after the transition has been applied. workflow.params.description:The description applied during or after the transition workflow.params.customfield_10001:Custom Field Value |
| 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 JSD issue, @internalComment=true/yes (case insensitive) marks the created comment as JSD internal. Otherwise @internalComment=* marks the comment as public (shared with customer). The directive overrides the Project Mapping's 'Service Desk Comment Mode' configuration. It is a good idea to create @internal @public aliases from @internalComent=true/false respectively.  |
Possible UC could be replying to a subtask issue with @JEMHCloud is trying to do the best possible to pre-validate every processor before send it to jira. E:G: if the priority is invalid, it will be ignored reporting the invalid value.
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: @Customer Request Type=bsd/get-it-help 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. @Organizations=Company A, 123 |
| Date of First Response | Not supported yet |
| Date Picker | custom date picker: 29/7/2011 (Using default format of d/MM/yy) or custom date picker: 29-Jul-2011 (Second directive defines the format, it's the field name following 'Format') |
| Date Time Picker | custom date time picker: 29/7/2011 10:50 PM (Using default format of dd/MM/yy h:mm a) or custom date time picker: 29-Jul-2011 10:50 PM (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 | custom labels: label1, label2 |
| Multi Remote Object Link | Not supported yet |
| Number Field | custom number: 10 |
| Project Picker (single project) | custom project picker: PKEY (Or name) |
| Radio Buttons | custom radio buttons: option1 |
| Remote ObjectLink | Not supported yet |
| Remote System Reference | Not supported yet |
| Select List (cascading) | custom cascading select: Parent Option, Child Option |
| Select List (multiple choice) | custom multiple select: Option 1, option 2 |
| Select List (single choice) | custom single list: Option 1 |
| Tempo Account | Account: SomeAccountKey |
| Text Field (multi-line) | custom textarea: line 1 |
| Text Field (read only) | custom text field read only: read only line |
| Text Field (single line) | custom text: only one line |
| Time In Status | Not supported yet |
| URL Field | custom url field: https://www.somehost.com/path |
| User Picker (multiple users) | custom multiple user picker: admin, someoneelse |
| User Picker (single user) | custom user picker: admin |
| UUID Field | Not supported yet |
| Version Picker (multiple versions) | custom multiple version: 2.1,2.3 |
| Version Picker (single version) | custom single version: 2.1 |