Post-functions

Owned by David Fischer (Unlicensed)
Last updated: Feb 09, 2023 by Daniel Barrow
8 min read

 

Using Post-functions in the Create transition

If you insert a Post-function in the Create transition, you must make sure that you place it:

  • JIRA up to 6.4.x: after the Creates the issue originally built-in function. The exception is any post-function that writes to a system field, such as Set Field Value (with a built-in field), Set Issue Security From User's Project Role, etc.
  • JIRA 7.0.0 and above: before the Creates the issue originally built-in function in most cases.

In general, when using a post-function in the Create transition, if it doesn't work as expected, try moving it around the Creates the issue originally built-in function.

Also, please note that any field based on issue links (such as some of those created by the Tempo plugin) are not available during the Create transition (because issue links are created after the initial issue creation).

Conditional execution of post-functions

Several of the following post-functions support conditional execution, in the way of an optional Groovy expression that must return true for the function to run.

This Groovy expression can reference any field value of the current issue. Access to issue field values is achieved by the following syntax:

issue.get("<field_ID>")

where <field_ID> is a built-in JIRA field ID (see this list) or a custom field ID (in the form customfield_nnnnn - see below for more information).

For complex conditions, you can also access the JIRA Issue object directly using the issueObject variable.

Finally, you can use the log variable to output information into atlassian-jira.log. For example:

log.error("Something went wrong");

To identify the custom field ID

  1. go to Administration -> Issues -> Custom Fields
  2. click on the "Configure" link for the custom field you're interested in
  3. in the URL of the Configure Custom Field page, note the number after "customFieldId=" and append it to "customfield_" to build the custom field ID

1 - Assign to role member (new in 1.2, updated in 3.0.1)

A worfklow function that assigns the current issue to the default member of the specified project role.

Since JIRA does not support the notion of a default member for project roles, the Assign to role member function identifies the default member of a project role by going through all the members of the project role looking for a User Property with the following two characteristics:

  • Property key: defaultAssignee
  • Property value: contains a comma-separated list of entries in the form ProjectKey -> *RoleName. *For example:  

 

TST -> Developers, JMWE -> Testers

 

For backward compatibility, the following two forms are also supported:

  • Property Key: {ProjectName}x{RoleName} (for example: CoolProjectxQAMembers)
  • Property value: "default" (without the quotes)

Or: (since 1.5.3)

  • Property Key: defaultAssignee{n}  (where n is a number from 1 up, for example: defaultAssignee1)
  • Property value: {ProjectName}x{RoleName} (for example: CoolProjectxQAMembers)

If no such member is found, the first member of the project role is used instead.

This can be used for scenarios like: "when a developer resolves the issue, assign the issue to the QA lead".

2 - Assign to last role member (new in 1.2) (updated in 1.5.1, 2.4.1 and 3.0.1)

A worfklow function that assigns the current issue to the latest Assignee (excluding the current one) who is a member of the specified project role.

When the function is executed it goes backwards through the change history of the issue. When it finds a user that belongs to the specified role, it assigns the issue to that user. Optionally, it can consider the Reporter and/or the Current Assignee in addition to previous assignees.

This can be used for scenarios like: "when QA fails assign the issue to the last developer who worked on it".

3 - Set Field Value to constant or Groovy expression Function (new in 3.1)

A worfklow function that sets the value(s) of a field to either a constant or the result of the evaluation of a Groovy expression.

When using Groovy, it is possible to access the issue (the one that triggers the function) through the "issue" and "issueObject" variables:

  • The "issue" object is a simple wrapper around the Issue that gives you a "get(String fieldName)" method to access fields directly (see the panel on "Conditional execution of post-functions" at the top of the page for details)
  • The "issueObject" is the actual com.atlassian.jira.issue.Issue object
  • The "log" object is a log4j logger that writes to atlassian-jira.log.

The return value of the script can be:

  • on object of the type expected by the field being set
  • a String that will be converted, if possible, to the type expected by the field being set
  • an array of String (String[]) that will be converted to a Collection of values of the type expected by the field being set

4 - Increase value of field Function

A workflow function that increases the value of a numerical field by one.

5 - Set field value from User Property value Function

A workflow function that sets a field to the value of a User Property.

A typical use is to store the country, or department, or other such information, of the Reporter of an issue into the issue itself (so that it can be displayed, searched, or used by the workflow).

When setting the Issue Security field, the user property must contain the numerical id of the Issue Security Level, which you can find by looking at the links associated with the Add/Default/Delete operations on the desired Security Level (on the Edit Issue Security Levels screen).

6 - Copy Field Value to Parent Function (new in 1.3.2)

A worfklow function that copies the value(s) of a field into the same field of the issue's parent issue.

7 - Set Field Value From Parent Function (new in 2.4)

A worfklow function that sets a field value to the value(s) of the same field of the issue's parent issue.

8 - Copy Field Value to Linked Issues Function (new in 3.0)

A worfklow function that copies the value(s) of a field into the same field of all issues linked to it through a specified link type.

Note that you can use this function to copy a field from an issue to its sub-tasks by using the built-in "jira_sub_outward" link type.

For GreenHopper users

You can use this function to copy field values from an Issue to its Epic, or from an Epic to its Issues.

9 - Set Field Value From Linked Issue Function (new in 3.0)

A worfklow function that sets a field value to the value(s) of the same field of an issue linked to it through a specified link type.

For GreenHopper users

You can use this function to set the value of a field from its Epic.

10 - Set Field Value Of Linked Issues Function (new in 3.1)

A worfklow function that sets the value(s) of a field on all issues linked to the current issue through a specified link type. The new value can be either a constant or the result of the evaluation of a Groovy expression.

Note that you can use this function to set a field of all sub-tasks by using the built-in "jira_sub_outward" link type, and of the parent issue by using the "jira_sub_inward" link type.

When using Groovy, it is possible to access both the source issue (the one that triggers the function) through the "issue" and "issueObject" variables, and the destination issue through the "linkedIssue" and "linkedIssueObject" variables (it will be evaluated once per linked issue to modify).
The "issue" object is a simple wrapper around the Issue that gives you a "get(fieldName)" method to access fields directly.
The "issueObject" is the actual com.atlassian.jira.issue.Issue object
The "log" object is a log4j logger that writes to atlassian-jira.log.

For GreenHopper users

You can use this function to set the value of a field on the Epic of an issue, or on all issues of an Epic.

11 - Copy Value From Field to Field Function (new in 2.3)

A workflow function that copies the value(s) of a field to another field of the same issue. It can optionally take the source value as it was before the transition (useful in case the user modified the source field during the transition screen). Since 2.4, it can also optionally merge multi-valued field values instead of replacing them.

12 - Add Field Value to Parent Function

A worfklow function that adds the value(s) of a multi-valued field (such as Fix version(s)) into the same field of the issue's parent issue.

13 - Set Issue Security From User's Project Role Function (new in 1.5)

A worfklow function that sets the issue security level based on the Project Role to which the current user belongs. This function can be used on the Create transition to set a different issue security level depending on whether the issue is being created by an internal user or by an external user (e.g. a customer).

 

To use this workflow function in the "Create Issue" transition, you must place it before the "Creates the issue originally" step.

14 - Transition Issue (new in 3.5.2)

A workflow function that triggers a named transition on the current issue. This can be used to move the current issue one step further in the workflow, if a condition is fulfilled.

Note that the transition can be specified by name, so that the transition can be found regardless of the parent issue's actual workflow, or by ID if disambiguation is required.

Also note that the transition should not be associated with a transition screen (which would not be displayed), especially if it includes required fields.

If you want to trigger an existing transition that normally uses a transition screen (such as the "Resolve Issue" transition), you should clone that transition, name it differently, remove the transition screen, and finally add the "Hide Transition" workflow condition so that this new transition remains hidden from users. And then trigger that new transition instead.

15 - Transition Parent Issue (new in 2.1)

A workflow function that triggers a named transition on the parent issue of the current sub-task.

Note that the transition can be specified by name, so that the transition can be found regardless of the parent issue's actual workflow, or by ID if disambiguation is required (since 2.4).

Also note that the parent transition should not be associated with a transition screen (which would not be displayed), especially if it includes required fields.

If you want to trigger an existing transition that normally uses a transition screen (such as the "Resolve Issue" transition), you should clone that transition, name it differently, remove the transition screen, and finally add the "Hide Transition" workflow condition so that this new transition remains hidden from users. And then trigger that new transition instead.

16 - Transition Linked Issues (new in 3.1.1)

A workflow function that triggers a named transition on issues linked to the current issue through a specified link type.

Note that the Transition Linked Issues post-function can also be used to transition sub-tasks. You just need to select the "jira_subtask_outward" link type.

The transition can be specified by name, so that the transition can be found regardless of the parent issue's actual workflow, or by ID if disambiguation is required.

Also note that the triggered transition (in the linked issues' workflow) should not be associated with a transition screen (which would not be displayed), especially if it includes required fields.

If you want to trigger an existing transition that normally uses a transition screen (such as the "Resolve Issue" transition), you should clone that transition, name it differently, remove the transition screen, and finally add the "Hide Transition" workflow condition so that this new transition remains hidden from users. And then trigger that new transition instead.

17 - Comment Issue (new in 3.3)

A workflow function that creates a Comment on the current issue. The text of the comment can be either a fixed text, or the result of the evaluation of a Groovy expression.

When using Groovy, it is possible to access the issue through the "issue" and "issueObject" variables.
The "issue" variable is a simple wrapper around the Issue that gives you a "get(fieldName)" method to access fields directly.
The "issueObject" variable is the actual com.atlassian.jira.issue.Issue object

18 - Comment Linked Issues (new in 3.6)

A workflow function that creates a Comment on linked issues. The text of the comment can be either a fixed text, or the result of the evaluation of a Groovy expression.

When using Groovy, it is possible to access the issue through the "issue" and "issueObject" variables, and each linked issue through the "linkedIssue" and "linkedIssueObject" variables.
The "issue" variable is a simple wrapper around the Issue that gives you a "get(fieldName)" method to access fields directly.
The "issueObject" variable is the actual com.atlassian.jira.issue.Issue object