1. Fidel Castro Armario
  2. JIRA Workflow Toolbox

Wiki

Clone wiki

JIRA Workflow Toolbox / Virtual Fields

JIRA Workflow Toolbox provides a set of special fields called Virtual Fields, making accessible the most interesting properties of issues, projects and users to every feature in the plugin. Virtual fields may be read and written by the plugin the same way ordinary custom fields are.

Writable virtual fields:

When a value is written into these fields, a feature or system field of the issue the field belongs to will be modified. These fields are also readable.

Field NameEffect of WritingAllowed String ValuesAllowed Numeric ValuesExamples
SummarySets issue Summarytext string trimmed to 255 charactersnumbers are cast to string-
DescriptionSets issue Descriptionunlimited text stringnumbers are cast to string-
AssigneeAssigns the issue to a useruser name (not user's full name) or name of project role. You can also use string unassigned to make the issue become unassigned.n/aChange assignee based on custom field

How to assign issue based on the value of a Cascading Select?

How to assign issue to a specific user based on a specific custom field value?

Turn issue unassigned when assigned to project leader

How can I set assignee depending on issue type?
ReporterUpdates issue Reporter to a different useruser name (not user's full name) or name of project rolen/a-
Due dateSets issue's system field Due Datedate-time in format defined at jira.date.time.picker.java.format, or as in JQL (yyyy/MM/dd HH:mm, yyyy-MM-dd HH:mm, yyyy/MM/dd, yyyy-MM-dd, or relative to current time using "w" (weeks), "d" (days), "h" (hours) or "m" (minutes)number of minutes relative to current time.2014-03-25 : date example

2015-01-31 14:35 : date with time example

- 4d 1h : 4 days and 1 hour before current time.

2w, 3d, 4h, 5m : 2 weeks, 3 days, 4 hours and 5 minutes after current time.

Setting Due Date to Current Date plus 2 Working Days

Setting Due Date to Current Date if not initialized at issue creation

Setting Due Date 6 natural days (or work days) earlier than a Date Picker custom field
PriorityUpdates the issue Priorityname of a Priority (e.g., Blocker, Critical, Major,...)(0 = highest priority, 1 = second highest,... n = lowestSet priority depending on a substring in issue Description

Propagate highest priority from blocked issues to blocking issues

2 examples of usage of Priority with post-function Set a field as a function of other fields

Setting priority for issues in certain status for longer than 24 hours
Original estimate (minutes)Sets original estimatecast from string to number will be attemptednumber of minutes30 : sets Original estimate to 30 minutes.

Original estimate (minutes) can be increased or decreased using post-function Mathematical and date-time expression calculator with formulas like: {00024} + 60 for increasing remaining estimate in 1 hour, or {00024} - {10000} for decreasing remaining estimate by the amount of minutes stored in custom field with code {10000}.
Remaining estimate (minutes)Sets remaining estimatecast from string to number will be attemptednumber of minutes30 : sets Remaining estimate to 30 minutes.

Remaining estimate (minutes) can be increased or decreased using post-function Mathematical and date-time expression calculator with formulas like: {00024} + 60 for increasing remaining estimate in 1 hour, or {00024} - {10000} for decreasing remaining estimate by the amount of minutes stored in custom field with code {10000}.
Total time spent (minutes)Sets time spent.cast from string to number will be attemptednumber of minutes30 : sets Time spent to 30 minutes.

Total time spent (minutes) can be increased or decreased using post-function Mathematical and date-time expression calculator with formulas like: {00024} + 60 for increasing remaining estimate in 1 hour, or {00024} - {10000} for decreasing remaining estimate by the amount of minutes stored in custom field with code {10000}.

Sum subtask's Time Spent (work logs) and then add it to a certain linked issue

Sum "Time Spent" in all subtasks of issues linked with issue link types "LinkA", "LinkB", "LinkC", etc

Setting "Total time spent = Current Date-Time - Date-Time of Last Update"
Add to time spent (minutes)
(since version 2.1.20)
Adds a number of minutes to current value of field "Total time spent (minutes)"cast from string to number will be attemptednumber of minutes60 : increases time spent in 1 hour.

- {10000} : decreases time spent by the amount of minutes stored in custom field with code {10000}.
ComponentsSets issue ComponentsComma separated list of component names.

Prefixes + and - can be used to add or remove (check or uncheck) single values or set of values.
n/a+ Web Site, User Management : adds the components Web Site and User Management to current issue, provided they exist in the project.

- Library A, Component B : removes the components Library A and Component B from current issue, provided they exist in the project.
Fixed versionsSets Fixed versionsComma separated list of version names.

Prefixes + and - can be used to add or remove (check or uncheck) single values or set of values.
numbers are cast to string+ 1.0, 1.1 : adds versions 1.0 and 1.1 to field Fixed versions.

- 2.0, 2.2 : removes versions 2.0 and 2.2 from field Fixed versions.
Affected versionsSets Affected versionsComma separated list of version names.

Prefixes + and - can be used to add or remove (check or uncheck) single values or set of values.
numbers are cast to string+ 1.0, 1.1 : adds versions 1.0 and 1.1 to field Affected versions.

- 2.0, 2.2 : removes versions 2.0 and 2.2 from field Affected versions.
EnvironmentSets issue Environmentunlimited text stringnumbers are cast to string-
Issue statusWill make the issue progress through the workflow to the written status, provided there is transition in the workflow from current status to the written status. It requieres that all conditions and validations in the transition are satisfied.name of a Status (e.g., Open, In Progress, Resolved,...)n/aResolved : will search for a transition from current issue's status to Resolved status. If conditions are satisfied, it will try to execute the transition. Then if validators are satisfied in that transition are satisfied, it will be executed, resulting in moving issue to Resolved status. Every post-function in the executed transition is also executed.

Automatically close subtasks when parent issue is closed.

Cancel child subtasks when current issue is cancelled

Automatically reopen Parent issue when one of its Subtasks is reopened
Issue status (delayed writing)Same as virtual field Issue status, with the only difference that actual writing is carried out after transition has finished in current issue. It's very useful when you need to make progress linked issues or subtasks blocked by "Sub-Task Blocking Condition" or "Condition/Validation on linked issues" due to current issue's status.name of a Status (e.g., Open, In Progress, Resolved,...)n/aAutomatically move issue to "In Progress" status once all its blocking issues are in "Closed" or "Resolved" statuses

Automatically close Parent Issue when all Subtasks are Closed
Execute transition
(since version 2.1.20)
Execute the transition whose name is written into this field, provided conditions and validators are matched, and the transition is available for current status. This field is an alternative to "Issue status".name of a transition (e.g., Open Issue, Start Progress, Resolve Issue, Close Issue,...)n/aClose Parent Issue when all Subtasks are Closed (solution 2)

Cancel child subtasks when parent issue is cancelled.
Execute transition (delayed execution)
(since version 2.1.20)
Same as virtual field "Execute transition", but execution is done once current transition has finished. This field is an alternative to "Issue status (delayed writing)"name of a transition (e.g., Open Issue, Start Progress, Resolve Issue, Close Issue,...)n/aClose Parent Issue when all Subtasks are Closed (solution 1)
ResolutionSets issue Resolutionname of issue Resolution (e.g., Fixed, Won't Fix, Duplicate, Incomplete,...)n/a-
LabelsSets LabelsComma separated list of labels. If label doesn't exist it is created.

Prefixes + and - can be used to add or remove (check or uncheck) single values or set of values.
numbers are cast to string+ jira, plugin : adds labels "jira" and "plugin" to the issue.

- scrum, web : removes labels "scrum" and "web" from the issue.
New labels
(since version 2.2.1)
Adds new labels to the issueComma separated list of labels. If label doesn't exist it is created.numbers are cast to string-
Attachments (only new attachments will be added)Adds new attachments coming from another issue keeping current attachments. Rejects duplicated attachments. Can be set by post-functions Write field on linked issues or subtasks and Write field on issues returned by JQL Query or Issue ListComma or blank separated list of issue keys whose attachments will be copied to current issue.n/aCMR-1 : adds to current issue the attachments in issue CRM-1 except if attachments are already in current issue.

CRM-2, HR-34, HR-50 : adds to current issue the attachments in issues CRM-2, HR-34 and HR-50 except if attachments are already in current issue.
Attachments (current attachments will be replaced)Replaces current's issue attachments with those coming from another issues. This field can be set by post-functions Write field on linked issues or subtasks and Write field on issues returned by JQL queryComma or blank separated list of issue keys whose attachments will be copied to current issue.n/aCMR-1 : copy attachments in CRM-1 to current issue, replacing the existing ones.

CRM-2, HR-34, HR-50 : copy attachments in CRM-2, HR-34 and HR-50 to current issue, replacing the existing ones.
Security levelSets issue Security Levelname of a Security Leveln/aPublic : sets security level to Public, provided this security level exists in the Security Scheme of the project.

Reserved : sets security level to Reserved, provided this security level exists in the Security Scheme of the project.

Setting Security Level depending on Reporter or Creator
Last commentUpdates the last comment added to the issue if it existsunlimited text string

Optionally parameter visibility can be added for setting comment visibility. To do it add : {visibility=visibility_value} at the end of the text. This parameter admits the same values as "Last comment's visibility restriction". (See example)
Since version 2.2
numbers are cast to stringWARNING: When writing into this field, please add your writer post-function AFTER "Add a comment to an issue if one is entered during a transition." post-function, since otherwise updated comment will be the one before last, instead of the last one. Example
Last comment's visibility restriction
Formerly called "Last comment's visibility"
Updates the visibility of the last comment in the issue if it exists. Can be used to set the visibility of a comment introduced with virtual field New commentname of a Project Role or name of a Group.

In Jira Service Desk it also admits values public and internal (without doble quotes), or alternatively jsd_public and jsd_internal to avoid name collision with existing project roles and user groups.
Since version 2.2
n/aDevelopers : for setting visibility to project role or group with name Developers.

jsd_internal : for setting JSD internal visibility.

jira-developers : for setting visibility to "jira-developers" user group.
New commentInserts a new comment into the issue. It doesn't trigger any event for email notifications.unlimited text string

Optionally parameter visibility can be added for setting comment visibility. To do it add : {visibility=visibility_value} at the end of the text. This parameter admits the same values as "Last comment's visibility restriction". (See example)
Since version 2.2
numbers are cast to stringThis is a comment only visible to developers group.: {visibility=jira-developers}

This is a comment only visible to Admin project role.: {visibility=Administrators}

This is a comment only visible to Jira Service Desk agents and collaborators.: {visibility=jsd_internal}

This is a comment also visible to Jira Service Desk customers.: {visibility=jsd_public}

Create a comment in subtasks

Creating a Jira Service Desk internal comment

Creating a JSD's internal comment on linked issues
New comment (sends email notifications)
(since version 2.2.22)
Inserts a new comment into the issue, triggering an event for sending email notifications.unlimited text string

Optionally parameter visibility can be added for setting comment visibility. To do it add : {visibility=visibility_value} at the end of the text. This parameter admits the same values as "Last comment's visibility restriction". (See example)
Since version 2.2
numbers are cast to string-
WatchersSets watchers of an issue. Can be used to add or remove watchers to linked issues, subtasks or issues returned by JQL, but requires to use operator '+' and '-'. Also can be used to copy watchers between issues.comma separated list of user names, group names or project roles names.

Prefixes + and - can be used to add or remove single users or set of users.
n/aalbert, richard, john : sets 3 users as watchers replacing current ones.

+ Developers, Administrators : adds every user in project roles or groups Developers and Administrators to current watchers.

- Testers, Administrators, + albert, richard : removes users in project roles or groups Testers and Administrators and adds users albert and richard as watchers.

Automatically become watcher of every issue blocking an issue assigned to us

Add watchers depending on the value of a custom field
New watchersAdds new watchers to an issue. Can be used to add new watchers to linked issues, subtasks or issues returned by JQL more easily that with virtual field Watchers, since you don't need to use operator '+'.comma separated list of user names, group names or project roles names.n/aalbert, richard, john : adds 3 watchers keeping current watchers untouched.

Add watchers depending on Security Level

Automatically become watcher of every issue blocking an issue assigned to us
Ephemeral string XThere are 5 ephemeral string fields. These fields are used to hold temporary text-string values returned by a post-function, which are used as input by another post-function. Once the transition execution has ended, all ephemeral fields are cleared, i.e., these fields can't be used to pass values from one transition to another.unlimited text string valuesnumbers are cast to string-
Ephemeral number XThere are 5 ephemeral number fields. These fields are used to hold temporary numeric and date-time values returned by a post-function, which are used as input by another post-function. Once the transition execution has ended, all ephemeral fields are cleared, i.e., these fields can't be used to pass values from one transition to another.String containing base 10 representation of a number, with dot character (i.e., .) as separator of integer and fractional partsintegers or real numbers, and also any Date-Time field (Date Picker, Date-Time Picker, Due Date, Created, etc.) which are stored as the number of milliseconds elapsed since January 1, 1970, 00:00:00 GMTExample of usage of an ephemeral number field to hold a date value

These fields are set by any of the following post-functions:

Values returned when reading virtual fields:

Field nameTypeValue returned when cast to stringExamples
SummaryText stringIssue summary.-
DescriptionText stringIssue description.-
AssigneeUserThe name of the user who has the issue assigned.albert.einstein
Assignee's full nameText stringName and surname of the user who currently has the issue assignedAlbert Einstein
Assignee's emailText stringEmail address of the user who currently has the issue assignedalbert.einstein@yahoo.com
ReporterUserThe name of the user who reported the issue. This field is editable, while Creator field isn't.albert.einstein
Reporter's full nameText stringName and surname of the user who created the issueAlbert Einstein
Reporter's emailText stringEmail address of the user who created the issuealbert.einstein@yahoo.com
Creator
(since version 2.1.20)
UserUser name of the user who actually creates the issue in JIRA. This field, unlike Reporter, can't be edited.richard.feynman
Creator's full name
(since version 2.1.20)
Text stringName and surname of the user who actually created the issue in JIRARichard Feynman
Creator's email
(since version 2.1.20)
Text stringEmail address of the user who actually created the issue in JIRArichard.feynman@gmail.com
Current userUserName of the user who is executing the transition.isaac.newton
Current user's full nameText stringName and surname of the user who is executing the transition.Isaac Newton
Current user's emailText stringEmail address of the user who leads the project the issue belongs to.albert.einstein@yahoo.com, isaac.newton@gmail.com
Current date and timeDate and TimeCurrent date and time of JIRA server's clock. When cast to string format defined at jira.date.time.picker.java.format is used.19/Mar/14 1:38 PM for jira.date.time.picker.java.format = dd/MMM/yy h:mm a

Define a time frame where transition execution is allowed

How to update Due Date with respect to current date?
Date and time of creationDate and timeDate and time when issue has been created. When cast to string format defined at jira.date.time.picker.java.format is used.19/Mar/14 1:38 PM for jira.date.time.picker.java.format = dd/MMM/yy h:mm a

Due Date is at least 5 workdays later than Creation Date and Time
Date and time of last updateDate and timeDate and time of the most recent issue update. When cast to string format defined at jira.date.time.picker.java.format is used.19/Mar/14 1:38 PM for jira.date.time.picker.java.format = dd/MMM/yy h:mm a
Date and time of latest status change
(since version 2.1.22)
Date and timeDate and time of the most recent status change in the issue. When cast to string format defined at jira.date.time.picker.java.format is used.19/Mar/14 1:38 PM for jira.date.time.picker.java.format = dd/MMM/yy h:mm a

Useful to find out for how much time is the issue in current status using expression: {00057} - {000158}, where {00057} = Current date and time and {000158} is Date and time of latest status change.

Block / Unblock Transition after Issue Rested for Certain Time in Current Status
Due dateDateField that can store a date with no time part, and is used to schedule issues. When cast to string format defined at jira.date.time.picker.java.format is used.19/Mar/14 for jira.date.time.picker.java.format = dd/MMM/yy h:mm a, since this field doesn't store time part.
Date and time of resolutionDate and timeDate and time of the most recent update of field Resolution. When cast to string format defined at jira.date.time.picker.java.format is used.19/Mar/14 1:38 PM for jira.date.time.picker.java.format = dd/MMM/yy h:mm a
PriorityPriorityName of the priority in Default language configured in the JIRA instanceBlocker
Critical
Major
Original estimate (minutes)NumberTime originally estimated for the issue expressed in minutes. It's a real number, so it may have a non-zero fractional part.-
Remaining estimate (minutes)NumberRemaining time estimated for the issue expressed in minutes. It's a real number, so it may have a non-zero fractional part.-
Total time spent (minutes)NumberWork time currently spent at the issue expressed in minutes. It's a real number, so it may have a non-zero fractional part.-
Work logged in transition (minutes)
(since version 2.1.20)
NumberNumber of minutes logged in current transition screen.This field can be used to enforce logging some time in transition screen.

Limiting the number of hours a user can log per day
Date and time of work logged in transition
(since version 2.1.34)
Date and timeDate and time introduced for the beginning of the work logged in current transition screen.Limiting the valid dates in the past for current worklogs
ComponentsComponentsComma separated list of component namesWeb Site, Authenticator, Statistics
Components leadersMulti userComma separated list of user namesalbert.einstein@yahoo.com, richard.feynman@gmail.com
Fixed versionsVersionsComma separated list of fixed versions1.0, 2.0, 2.1
Fixed versions with detailsText stringA text with a line for each fixed versions. Each line contains the following information separated by characters '#': name of version, description, release date and archive situation1.0 # First release # RELEASED ON 28/Mar/14 12:00 AM # ARCHIVED
Number of fixed versionsNumberNumber of fixed versions in current issue.-
Affected versionsVersionsComma separated list of fixed versions1.0, 2.0, 2.1
Affected versions with detailsText stringA text with a line for each affected versions. Each line contains the following information separated by characters '#': name of version, description, release date and archive situation1.0 # First release # RELEASED ON 28/Mar/14 12:00 AM # ARCHIVED
Number of affected versionsNumberNumber of affected versions in current issue.-
Number of votes receivedNumberNumber of votes received by the issue.-
Keys of subtasksText stringComma separated list of issue keys.CRM-23, CRM-26, CRM-31
Number of subtasksNumberNumber of subtasks of current issue.-
Keys of linked issuesText stringComma separated list of issue keys.CRM-13, HR-12, SDESK-45
Number of linked issuesNumberNumber of issues linked to current issue.-
EnvironmentStringField to describe the environment where the issue has occurred.-
AttachmentsAttachmentsComma separated list of file names of all files attached to the issue.file1.txt, readme.pdf, screenshot.png

Ensure that the issue has at least one attachment.

Rejecting duplicated file names in attachments
Attachments with detailsText stringComma separated list of file names with its mime types and sizes in Kbytes, for every file attached to the issue.file1.txt (text/plain, 5.14 KB), readme.pdf (application/pdf, 179.8 KB), screenshot.png (image/png, 5.449 KB)
Number of attachmentsNumberNumber of files attached to current issue.-
Transition's attachmentsAttachmentsComma separated list of file names of all files attached to the issue in current transition's screen.file1.txt, readme.pdf, screenshot.png
Transition's attachments with detailsText stringComma separated list of file names with its mime types and sizes in Kbytes, for every file attached in current transition's screen.file1.txt (text/plain, 5.14 KB), readme.pdf (application/pdf, 179.8 KB), screenshot.png (image/png, 5.449 KB)
Number of transition's attachmentsNumberNumber of files attacher to current issue in transition screen. It's useful to enforce attachments in transition screen, by means of "Boolean validator with math, date-time or text-string terms".Update checkboxes custom field if a file is attached in transition
Recent attachments
(since version 2.2.20)
AttachmentsComma separated list of file names of all files attached to current issue in the last minute (60 seconds).file1.txt, readme.pdf, screenshot.png

NOTE: This is an alternative to Transition's comments, which doesn't work for files attached in a transition triggered from JSD Portal.
Recent attachments with details
(since version 2.2.20)
Text stringComma separated list of file names with its mime types and sizes in Kbytes, for every file attached to current issue in the last minute (60 seconds).file1.txt (text/plain, 5.14 KB), readme.pdf (application/pdf, 179.8 KB), screenshot.png (image/png, 5.449 KB)

NOTE: This is an alternative to Transition's comments with details, which doesn't work for files attached in a transition triggered from JSD Portal.
LabelsLabelsBlank separated list with all the labels of the issue.web customer java mobile
Number of labelsNumberNumber of labels in current issue.-
Issue keyText stringIssue keyCRM-25
HR-52
SDESK-1
Issue typeIssue typeName of issue's Issue Type in JIRA's default languageBug
Improvement
New Feature
Task

Restricting subtask type creation depending on parent issue status
Issue statusIssue statusName of current status of the issue in JIRA's default language.Open
In Progress
Resolved
Issue status category
(since version 2.1.20)
Status categoryName of the category in JIRA's default language.To Do
In Progress
Done
Previous issue status
(since version 2.1.20)
Issue statusName of the status the issue was just before current one. The name is shown in JIRA's default language.Open
In Progress
Closed
Previous issue status category
(since version 2.1.20)
Status categoryName of the category of the status the issue was just before current one. The name is shown in JIRA's default language.To Do
In Progress
Done
Current transition
(since version 2.2.26)
Text stringWhen used in a validation or a post-function: the name of the transition being executed. In other cases: a comma separated list with the names of the transitions departing from current status.In a validation: Start Progress

In a condition: Start Progress, Resolve Issue, Close Issue
Target status
(since version 2.2.26)
Text stringWhen used in a validation or a post-function: the name of the target status of the transition being executed. In other cases: a comma separated list with the names of the target status of the transitions departing from current status.In a validation: In Progress

In a condition: In Progress, Resolved, Closed
ResolutionResolutionThe name of the resolution currently set at the issue, or empty string if Resolution is not set. The name of the resolution is shown in JIRA's default language.Resolved
Won't fix
Cancelled
Security levelSecurity levelName of the security level the issue currently has.Classified
Last commentText stringLast comment entered in the issue.-
Last comment's visibility restrictionText stringName of a group or project role the visibility of the last comment entered in the issue is restricted to. If no restriction is applied to the comment, this field is returns an empty string. For Service Desk's special Internal visibility restriction, string "Internal" is returned. This field can be used to check visibility restriction of field entered in transition when it exists.

When using a post-function for setting this field in order to set visibility restrictions over the comment entered in the transition screen, always insert the post-function after post-function "Add a comment to an issue if one is entered during a transition.", like in this example.
-
Last commenter
(since version 2.1.33)
UserName of the user who entered the last comment in the issue.galileo.galilei
Transition's commentText stringComment entered in transition screen. This field can be used to make comment mandatory in transition screen, or to validate the content of comment entered in a transition.-
WatchersMulti-userComma separated list of user names of current watchers of the issue.albert.einstein, richard.feynman, galileo.galilei
Project keyText stringProject Key of the project the issue belongs to.CRM, HR, SDESK
Project nameText stringName of the project the issue belongs to.Customer Relationship Management
Project descriptionText stringField Description of the project the issue belongs to.-
Project URLText stringField URL of the project belongs to.http://www.workflowarts.com
Project categoryText stringName of the Category of the project the issue belongs to.-
Project leaderUserName of the user who leads the project the issue belongs to.galileo.galilei
Project leader's full nameText stringName and surname of the user who leads the project the issue belongs to.Galileo Galilei
Project leader's emailText stringEmail address of the user who leads the project the issue belongs to.galileo.galilei@me.com
Rest of issues in the projectText stringComma separated list of issue keys in the project except current issue's key.CRM-1, CRM-2, CRM-3, CRM-4
Workflow schemeText stringThe name of the workflow scheme of the project current issue belongs to.-
JIRA base URL
(since version 2.2.12)
Text stringReturns the base URL of current JIRA instance.-
Customer Request Type Name
(since version 2.2.28)
Text stringThe name of the Customer Request Type.Field Customer Request Type returns the key, thus this read-only field is introduced in order provide a means to get the name of the Customer Request Type.
Sprint ID
(since version 2.2.29)
Text stringThe internal ID for the sprint of current issue. This value can be used for setting field Sprint in other issues.-
Tempo Account Key
(since version 2.2.28)
Text stringThe key of Tempo Timesheets' Account field.Field Account returns the numerical ID, thus this read-only field is introduced in order provide a means to get the Account's Key.
Tempo Account Name
(since version 2.2.28)
Text stringThe name of Tempo Timesheets' Account field.Field Account returns the numerical ID, thus this read-only field is introduced in order provide a means to get the Account's Name.
Sprint Start Date
(since version 2.2.40)
DateSprint's start date.-
Sprint End Date
(since version 2.2.40)
DateSprint's end date.-

For every virtual and custom field in a subtask, there is also another virtual field representing the same field in its parent issue, making it very easy to read and write parent's issue fields.

Updated