Supported fields for use with Directives
Jira Core
The intention is to be able to set anything on a JIRA Issue. Comments and attachments are implicitly supported during issue creation and comment.
Multiple values are typically support with CSV, e.g. @key=Value1,Value2,Value3
Field | Description/notes | Use in create | Use in comment |
---|---|---|---|
custom-field | Values are considered as CSV where mulitple values are possible (eg selects, multi picker fields), in such cases, comma ' , ' cannot form part of values to be set. Custom fields can be manipulated in two ways:
| ||
project | numeric (e.g. | ||
priority | numeric (e.g. 4) or text name (e.g. critical) | ||
issueType | numeric (e.g. 12) or text name (e.g. Feature Request) | ||
issueType.status since 3.3.56 | Requires an numeric (e.g. 6) or text name (e.g. Closed) It’s possible to migrate an existing Issue Type with a status when this directive is used in conjunction with the For example (in the @ prefix field processor): Status migration will only be processed during commenting. If an invalid status is found or issue failed to transition to the supplied Status value; then issue will proceed as original issue type and workflow state. | ||
components | A CSV capable field. Can be numeric (e.g. 100020) or textual name (e.g. My Magic Component) | ||
viewable | String value matching a group or role name, used to restrict the visibility of comments | ||
environment | String | ||
reporter | userid or email address of given user in JIRA | ||
assignee | userid or email address of given user in JIRA, who is 'assignable' | ||
summary | String (single line) | ||
description | String (multiple lines) | ||
watchers | Comma Separated Variable list of userid's, in Jira | ||
dueDate | Users can override the default (ISO standard) SimpleDateFormat string | ||
workEstimate | of format 1w7d12h30m, or any derivative JIRA 6 requires spaces between values. When supplied in the subject it needs quoting like: | ||
linkto | Issue Linking more information on Issue Links here: https://confluence.atlassian.com/adminjiraserver/configuring-issue-linking-938847862.html , FormatLegend
directionType:destinationIssue/linkTypeProperty Examplesto
from
to+from
multiple links
| ||
fixVersions | 1.3,2.1 | ||
affectsVersions | 1.0,1.1,2.0 | ||
vote | true (only value to make sense/false) | ||
securityLevel | Long value, e.g. 12345. |
Jira Software
Field | Description/Notes | Use in Create | Use in Comment |
---|---|---|---|
epic name | Required when creating an issue of type "Epic" | ||
epic link | Required in order to link an issue to a parent Epic. The value used is the name of the epic you are linking it to. | ||
epic colour | The colour pre-set used for the Epic. The values are |
Jira Service Management
Field | Description | Create | Comment |
---|---|---|---|
organizations | Sets the Organizations field on requests. The value can be either the ID or name of one or more Organizations. Multiple values should be comma separated. | ||
internalComment | Used to set whether a comment is internal (private, not seen by customers) or not. Can only be used by Agent users. Value is boolean ( |
Other
Referring to a related issue key
Field | Description | Use in create | Use in comment |
---|---|---|---|
issueKey | this Directive can identify an issue directly, e.g. with a value of |
Sub-tasks
Issues can be created nominating a parent issue such that they become a child of that issue. Restrictions are that they get created in the same project. Its possible to set components if required.
Field | Description/notes | Use in create | Use in comment |
---|---|---|---|
parentIssueKey | value indicates issue to create new task under |
Issue Templates
Issues can be created that refer to another, from which most properties will be taken on 'template' style. In addition, that template issues description can use a special markup %comment%
that will be replaced by the incoming email body part, allowing nested content to be generated. An example would be issueTemplate=ABC-123
. Whilst this structure will work fine in body Directives, it will not work in the Subject, as it will be found by Jira for commenting purposes. The workaround is to use Aliases, which may be a better all-round solution, as it then isolates the issue used as a template from people using it, for example, a range of aliases could be set-up, such as @support
, @defect
, @documentation
etc.
Field | Description | Use in create | Use in comment |
---|---|---|---|
issueTemplate | uses fields from the given issue during issue creation, allowing defaulted custom field values and more |
Example Description of a template issue, showing how to get incoming description injected:
This is an example message...
*Thanks for the comment:*
{quote}
%comment%
{quote}
Thanks for calling...
Workflow
The following directives can be used to transition through an issues workflow.
Field | Description/notes | Use in create | Use in comment |
---|---|---|---|
workflow | value indicates the workflow step, can be exact text match or first word match (see FAQ), e.g. | ||
workflow.<parameter> | keys with suffixes of workflow. are interpreted as parameters to the given workflow transition, otherwise defaults will be used (see FAQ). For example, |
Example of workflow manipulation with the @ Prefix Field Processor
MIME-Version: 1.0
Received: by 10.223.112.12 with HTTP; Sat, 18 Jun 2012 22:42:26 -0700 (PDT)
Date: Sun, 19 Jan 2016 17:42:26 +1200
Message-ID: <BANLkTinB8fd7nfdsp7dBoQ@mail.gmail.com>
Subject: ISSUE-5
From: user@company.com
To: jira-mail@company.com
Content-Type: text/plain; charset=UTF-8
@workflow=close
@workflow.resolution=done
Work Logs
It is possible to add work logs, update time remaining and set work log visibility. Keys are case-insensitive.
Field | Description/notes | Use in create | Use in comment |
---|---|---|---|
wl.timeSpent | Sets logged work duration to be set in normal | ||
wl.startDate | Set logged work start date in system default date format (TODO link to Jira property) | ||
wl.newEstimate | Sets the new estimate of effort for the work, value format | ||
wl.keepEstimate | If set true will keep the existing estimate unmodified, when logging | ||
wl.viewable.role | Enables Project Role visibility restrictions for work logs to be set, Name or ID can be used | ||
wl.viewable.group | Enables visibility restrictions for work logs to be set (NOTE: must be enabled through |
Attachments
All attachments are automatically added to created issues in either create or comment mode.
Custom Fields
Simple custom fields just need to be picked out by name as a key, e.g. Date Time: 28/Jan/09 08:00 am
. The value is the text->object encoding supported by the Custom Field.
Field Extensions
Field | Description/notes | Use in create | Use in comment |
---|---|---|---|
ccHandling | values are | ||
ccHandlingTargetCustomFieldName | Defines the name or ID of a Custom Field that will have cc: resolvable users added to | ||
ccusers | This field can be used in addition to the standard email cc:, it is a CSV formatted value, identifying users by ID/email. The provided values are processed according to system configuration values ccHandling and ccHandlingTargetCustomFieldName |