Clone wiki

JIRA Workflow Toolbox / post-functions / Write Field on Selected Issues

Write field on issues returned by JQL Query or Issue List

This post-function is used for setting fields in issues selected by a JQL Query or an Issue List expression, using any of the following source values:

  • Field in current issue: the value a field in current issue.
  • Parsed text (basic mode): a text composition where value of fields in current issue can be inserted.
  • Parsed text (advanced mode): a string expression where we can use values of fields in current issue (syntax %{nnnnn}), and in JQL selected issues (syntax ^%{nnnnn}). Here we can use all the functions available in the plugin's parser.
  • Math or Date-Time expression: an expression returning a numeric value where we can use values of fields in current issue (syntax {nnnnn}), and iin JQL selected issues (syntax ^{nnnnn}). Here we can use all the functions available in the plugin's parser.

Issue Selection Modes:

There are 2 different modes for selecting the issues whose field values are going to be set: JQL query and Issue List expression.

1. JQL Query:

In this issue selection mode we use JQL, which is a language provided by JIRA for doing advanced issue searching.

You can insert field codes with format %{nnnnn} in your JQL query. These field codes will be replaced with the values of the corresponding fields in current issue at execution time, and the resulting JQL query will be processed by JIRA JQL Parser. This way you can write dynamic JQL queries that depend on values of fields of current issue. Example: issuetype = "%{00014}" AND project = "%{00018}" will return issues in same project and with same issue type as current issue.

When you write your JQL for selecting the issues, take into account the following advices:

  • If field values are expected to have white spaces or JQL reserved words or characters, you should write field code between quotes (double or simple). Example: summary ~ "%{00021}" will return issues with current user's full name. As full name can contain spaces, we have written the field code between double quotes.
  • In general we will write field codes between quotation marks, since in most cases it doesn't hurt and it's useful for coping with field values containing white spaces or reserved JQL words. Anyway, there is an exception to this general rule: when our field contains a comma separated list of values, and we want to use it with JQL operator IN. In those cases we will not write the field code between quotes, since we want the content of the field to be processed as a list of values, not as a single string value.

    Example: Let's assume that "Ephemeral string 1" (field code %{00061}) contains a comma separate list of issue keys like "CRM-1, HR-2, HR-3". JQL Query issuekey in ("%{00061}") will be rendered in runtime like issuekey in ("CRM-1, HR-2, HR-3"), which is syntactically incorrect. On the other hand, JQL Query issuekey in (%{00061}) will be rendered in runtime like issuekey in (CRM-1, HR-2, HR-3), which is correct.

Disabling JQL Syntax Pre-Checking:

When we enter our JQL query, a syntax pre-checking is carried out in order to verify that it's correctly written. But when we insert field codes in our JQL query, the definitive form of the query that will be executed is unknown, since it depends on the actual values of the fields in runtime. In these cases the syntax pre-checking is done with speculative values given to the fields, and it might happen that fake syntax errors are reported. In order to inhibit the JQL syntax pre-checking you should enter // at the beginning of the line. Those characters will be removed in the actual JQL query that will be executed.

Example:
Example of syntax pre-check inhibition

2. Issue List expression:

In this issue selection mode we use an issue list expression according to the syntax of the plugin's parser. Here you can find a collection of Issue List selection examples.

Additional Options:

  • Don't overwrite target field if it's already set: when checked, this parameter will make the post-function do nothing in case target field is not empty in current issue.
  • Run as: JIRA user post-function is going to be executed as. This parameter can be set to a fixed user (e.g. "john.nash"), or to a user field (e.g. "Reporter", "Assignee", etc). This parameter is particularly important in this feature since JQL query will return issues according to the browse permission this user has in the different project of the instance of JIRA.

Example 1: Adding attachments uploaded in current issue's transition to other issues

Files attached to current issue in current transition's screen will be added to issues in status "In Progress" and assigned to the same user that has current issue assigned:

./post-functions/write-selected-issues/ex1-conf-1.png

JQL query used is: assignee = "%{00003}" AND status = "In Progress"

Note that:

  • %{00003} if field code for Assignee.

Once configured, your post-function will look like this:

./post-functions/write-selected-issues/ex1-final-conf.png

Example 2: Add 3 days to due date in issues blocked by current issue

Due date of issues linked to current issue with "blocks" issue link type, will be added 3 days, skipping weekend's days. In case the Due date is not set in blocked issues, it will be set using current issue's due date as value.

Described action will be carried out only into blocked issues in statuses "Open" or "In Progress".

./post-functions/write-selected-issues/ex2-conf-1.png

Note that:

  • Source value: ^{00012} != null ? addDaysSkippingWeekends(^{00012}, 3, LOCAL) : {00012}, where {00012} represent's due date in current issue, and ^{00012} due date in blocked issues. We use conditional operator ? : in order to check whether due date is set in blocked issues, and then select the correct source value according to it.
  • Issue List: filterByStatus(linkedIssues("blocks"), "Open, In Progress"). With this issue list expression we are selecting issues blocked by current issue, which are also in statuses "Open" or "In Progress".


Once configured, your post-function will look like this:

./post-functions/write-selected-issues/ex2-final-conf.png

Example 3: Set priority in non-resolved tasks and subtasks to epic's priority if it's higher

This post-function is intended to be executed in Epic's workflow, i.e., current issue is an Epic.

./post-functions/write-selected-issues/ex3-conf-1.png

Note that:

  • Source value: min({00017}, ^{00017}), where {00017} represent's priority of current issue (i.e., Epic), and ^{00017} priority of tasks and subtasks. Note that the lower the value, the highest the priority. Highest priority is 0.
  • Issue List: filterByResolution(subtasks() UNION linkedIssues("is Epic of"), ""). Here we use function filterByResolution() to select only those issues with empty resolution.


Once configured, your post-function will look like this:

./post-functions/write-selected-issues/ex3-final-conf.png

Other Usage Examples

Related Features

Updated