When running Groovy scripts, JMCF makes contextual information available to your script through built-in variables and functions. This document details them. Note that you can also define custom variables in your Groovy script.
On this page:
Table of Contents
Variables availability
The variables in JMCF are available on the custom field configuration screen when you write a Groovy script in the Groovy Formula field to return a value expected by a calculated custom field.
...
| Variable name | Type | Description |
|---|---|---|
Issue | The | |
| 175211280 | String | The value of the calculated field |
175211280 | TextUtils | textutils is a utility object of class TextUtils providing useful methods to manipulate text and HTML |
175211280 | Logger | The log variable is a Logger instance that writes into atlassian-jira.log (useful for debugging) |
175211280 | NumberTool | A NumberTool instance that can be used to format number values. |
...
The value represents the value of the calculated field returned by the Groovy script in the custom field configuration. This is applicable only while customizing the display of a Calculated (Scripted) Number custom field type to format it using the 175211280 variable. The data type of the variable is a Double.
...
The numberTool variable is a NumberTool instance that can be used to format the value of the calculated field returned by the Groovy script in the custom field configuration. This is applicable only while customizing the display of a Calculated (Scripted) Number custom field type to format it.
For example: If the value of a calculated number custom field is 22 you can format it using the numberTool variable available in the Groovy editor of the Format Expression field.
...
The value is formatted to $40.
To add an IMG tag to display an icon to the left of the number:
| Code Block |
|---|
"<img src='/images/icons/priority_trivial.gif'> "+numberTool.format(value); |
...
The textutils variable is a utility object of class TextUtils providing useful methods to manipulate text and HTML.
...
So when the issue is unassigned, the warning message is displayed in the atlassian-jira.log file.
Custom variables
In addition to the above variables, you can also define your own variables in the Groovy script.
For example, Condition to check whether the Fix Version/s has a particular version.
...
| Variable name | Type | Description |
|---|---|---|
issueObject | Issue | Deprecated. The issueObject variable is a synonym for the issue variable. |
Functions
Functions availability
The functions in JMCF are available on the custom field configuration screen when you write a Groovy script in the Groovy Formula field to return a value expected by a calculated custom field.
Available functions
Function Name | Returns | Description |
|---|---|---|
jqlSearch("<JQL expression>", <maxResults>) | List<Issue> | Search for issues using JQL |
Component/Service | Global function to get a Component/Service from Jira or any loaded add-on |
jqlSearch("<JQL expression>", <maxResults>)
jqlSearch("<JQL expression>", <maxResults>)is a simple function that you can use to search for issues using a JQL. The function expects the following:
- JQL expression:A JQL query
- maxResults:maximum number of issues to return
When you pass a valid JQL query and number of issues, the function returns a List<Issue> of issues that match the JQL.
Example: Calculate the Story points of all issues of a specific project and display them on the current issue as Total Story points.
| Code Block |
|---|
issueCount = ComponentAccessor.getIssueManager().getIssueCountForProject("<Project ID>")
issues = jqlSearch("project = TP and cf[10006] >= 0",issueCount.intValue())
storyPoints = 0
issues.each{
storyPoints += it.get("Story Points")
}
storyPoints |
getComponent(Class interface)
getComponent(Class interface) is aglobal function to get a Component/Service from Jira or any loaded add-on. The function expects a Class interface as the parameter.
| Code Block | ||||
|---|---|---|---|---|
| ||||
import com.atlassian.greenhopper.service.rapid.view.RapidViewService def RapidViewService = getComponent(RapidViewService); |
Some more examples:
| Code Block | ||||
|---|---|---|---|---|
| ||||
def issueManager = getComponent(com.atlassian.jira.issue.IssueManager.class) |
| Code Block | ||||
|---|---|---|---|---|
| ||||
def SprintService = getComponent(com.atlassian.greenhopper.service.sprint.SprintService.class) |
secondsBetween(Date from, Date to)
secondsBetween(<Date from>, <Date to>) is a global function that returns a Long representing the number of seconds between two Date objects. It returnsnullif one of the two parameters isnull. For example:
Code Block language groovy linenumbers true secondsBetween(issue.created, issue.duedate)
returns the number of seconds between the issue creation and the due date.
Code Block language groovy linenumbers true secondsBetween(issue.created, new Date())
returns the number of seconds from the issue creation to now.
secondsBetween(Date from, Date to, String roundTo)
secondsBetween(<Date from>, <Date to>, String roundTo) is a global function that returns a Long representing the number of seconds between two Date objects optionally rounding the number of seconds to the nearest minute, hour, day or week. It returnsnullif one of the two parameters isnull.
<roundTo>: is either "max" or one of "weeks", "days", "hours", "minutes" (or their equivalent: "w", "d", "h", "m"). If the rounding is "max", it will be rounded to the largest unit reached by the duration. For example:
- If
secondsBetween(issue.created, issue.duedate)returns 2 hours 51 minutes,Code Block language groovy linenumbers true secondsBetween(issue.created, issue.duedate, "max")
will be rounded to 10800 seconds (3*60*60 seconds) and will be displayed as 3 hours.
If
secondsBetween(issue.created, issue.duedate)returns 65328 secondsCode Block language groovy linenumbers true secondsBetween(issue.created, issue.duedate, "h")
will be rounded and displayed as 64800 seconds
workdaysBetween(Date from, Date to)
workdaysBetween(<Date from>, <Date to>) is a global function that returns aLongrepresenting the number of work days (excluding Saturdays and Sundays) between two Dateobjects. It returnsnullif one of the two parameters isnull. For example:
Code Block language groovy linenumbers true workdaysBetween(issue.created, issue.duedate)
returns the number of days between the issue creation and the due date
Code Block language groovy linenumbers true workdaysBetween(issue.created, new Date())
returns the number of days from the issue creation to now.
asUser(String username){codeblock}
asUser() is a simple global function that runs a code impersonating a user. During the execution of the code block, the current user will be set to the user with the specified username. The function expects the following:
- username: Username of the user to impersonate
- codeblock: Code block to run while impersonating a user
For example:
| Code Block |
|---|
asUser("jdoe") {
ComponentAccessor.jiraAuthenticationContext.loggedInUser.name
} |
returns jdoe, regardless of who the current user is.
Note that the current user will be restored when the code block is exited.
asUser(ApplicationUser user){codeblock}
asUser(ApplicationUser user) is a simple global function that runs a code impersonating a user. During the execution of the code block, the current user will be set to the specified user. The function expects the following:
- ApplicationUser: User to impersonate
- codeblock: Code block to run while impersonating a user
For example:
| Code Block |
|---|
asUser(issue.assignee) {
ComponentAccessor.jiraAuthenticationContext.loggedInUser?.name
} |
returns the name of the assignee of the issue, regardless of who the current user is.
Note that the current user will be restored when the code block is exited.