Please visit our Support Page for more information. |
The JIRA Misc Custom Fields plugin's objective is to provide several new types of custom fields for use in custom JIRA workflows as well as useful JQL functions.
Included custom fields:
Included JQL function:
The plugin is a "type TWO" plugin, which means that the plugin can be installed by copying it to jira-home/plugins/installed-plugins or, better yet, using the excellent Atlassian Universal Plugin Manager.
If you are using complicated (like recursive) formulas in calculate custom fields, and you are running on a large server, you might need to tune JMCF's thread pool as documented in JMCF-173. |
The formula is written using the BeanShell language, and should be included in the field description inside an html comment (so that it remains invisible when showing the field description), preceded by the following keyword: @@Formula: (note the colon at the end). For example:
<!-- @@Formula: formula goes here --> |
You can naturally include the real description of the custom field as well. For example:
This field represents the number of Affected Versions. <!-- @@Formula: issue.get("versions").size() --> |
The formula itself is a Java-style expression that can reference any issue field value, include arithmetic operators as well as any other Java operator, and Java method calls (such as the .size() example above). Access to issue field values is achieved by the following syntax:
issue.get("<field_ID_or_Name>") |
where <field_ID_or_Name> is either a built-in JIRA or custom field ID (the latter in the form customfield_nnnnn), or a field name. See this page for details.
You can also access the JIRA Issue object using the issueObject
variable.
|
Note that you must make sure the formula returns a number, or null.
If the calculated field does not show up on the view issue screen, you must make sure the formula isn't raising an error. For that, you must look at the end of the JIRA log file (atliassian-jira.log) right after displaying the issue (displaying an issue will always force calculated fields to be re-calculated). You can also include logging code into your script using the "log" object. For example:
We recommend you write to the logs using the "log.error()" method because ERROR-level logs are always written out to atlassian-jira.log (whereas DEBUG-level logs are filtered out by default). |
To add two custom fields, such as "Business Value" and "Technical Value" to get an "Overall Value":
<!-- @@Formula: (issue.get("customfield_10114") != null ? issue.get("customfield_10114") : 0) + (issue.get("customfield_10150") != null ? issue.get("customfield_10150") : 0) --> |
You can also specify custom formatting for the value of the Calculated Number field. In the Description field, add your formatting formula using the following syntax:
<!-- @@Format: formula goes here --> |
The formula itself is a Java-style expression that can reference the value returned by the formula using the value variable. You can also use the numberTool object to format the number value:
numberTool.format(value) |
To display an icon to the left of the field value depending on the field value:
<!-- @@Format: if (value > 21) return "<img src='/images/icons/priority_trivial.gif'> "+numberTool.format(value); else if (value >= 10) return "<img src='/images/icons/priority_major.gif'> "+numberTool.format(value); else return "<img src='/images/icons/priority_blocker.gif'> "+numberTool.format(value); --> |
The formula is written using the BeanShell language, and should be included in the field description inside an html comment (so that it remains invisible when showing the field description), preceded by the following keyword: @@Formula: (note the colon at the end). See Calculated Number Field above for details.
Note that you must make sure the formula returns a String, or null.
When creating a Calculated Text Field, you can choose between the standard Free Text Searcher and the new Exact Text Searcher (Statistics-compatible). The latter should be used if you need either of the following:
The formula is written using the BeanShell language, and should be included in the field description inside an html comment (so that it remains invisible when showing the field description), preceded by the following keyword: @@Formula: (note the colon at the end). See Calculated Number Field above for details.
Note that you must make sure the formula returns a java.util.Date, or null.
You can also specify a date/time format for the value of the Calculated Date/Time field. In the Description field, add the name of the date/time format using the following syntax:
<!-- @@Format: <format_name> --> |
where <format_name>
is one of the constants found here: https://developer.atlassian.com/static/javadoc/jira/reference/com/atlassian/jira/datetime/DateTimeStyle.html
The transition(s) should be indicated in the field description inside an html comment (so that it remains invisible when showing the field description), preceded by the following keyword: @TransitionId: or @TransitionName: (note the colon at the end). For example:
<!-- @TransitionId: transition ID --> |
or
<!-- @TransitionName: transition name --> |
If you use @TransitionId, you can specify a list of transition IDs, separated by commas (new in 1.2.5 and 1.5.2):
<!-- @TransitionId: transition_ID_1,transition_ID_2 --> |
You can naturally include the real description of the custom field as well. For example:
This field represents the date and time of the Resolution of this issue. <!-- @TransitionId: 5 --> <!-- @Execution: last --> |
You can also specify whether to capture the first or last transition execution, using the @Execution: keyword followed by first or last. For example:
<!-- @Execution: first --> |
If you don't specify anything, the last execution will be captured.
The transition(s) should be indicated in the field description inside an html comment (so that it remains invisible when showing the field description), preceded by the following keyword: @TransitionId: or @TransitionName: (note the colon at the end). For example:
<!-- @TransitionId: transition ID --> |
or
<!-- @TransitionName: transition name --> |
If you use @TransitionId, you can specify a list of transition IDs, separated by commas (new in 1.2.5 and 1.5.2):
<!-- @TransitionId: transition_ID_1,transition_ID_2 --> |
You can naturally include the real description of the custom field as well. For example:
This field represents the Resolver of this issue. <!-- @TransitionId: 5 --> <!-- @Execution: last --> |
You can also specify whether to capture the first or last transition execution, using the @Execution: keyword followed by first or last. For example:
<!-- @Execution: first --> |
If you don't specify anything, the last execution will be captured.
The transition(s) should be indicated in the field description inside an html comment (so that it remains invisible when showing the field description), preceded by the following keyword: @TransitionId: or @TransitionName: (note the colon at the end). For example:
<!-- @TransitionId: transition ID --> |
or
<!-- @TransitionName: transition name --> |
If you use @TransitionId, you can specify a list of transition IDs, separated by commas (new in 1.2.5 and 1.5.2):
<!-- @TransitionId: transition_ID_1,transition_ID_2 --> |
You can naturally include the real description of the custom field as well. For example:
This field represents the Resolver of this issue. <!-- @TransitionId: 5 --> <!-- @Execution: last --> |
A date/time field that returns the last time a field's value was changed.
The field whose last modification date should be returned must be indicated in the field description inside an html comment (so that it remains invisible when showing the field description), preceded by the following keyword: @@Field: (note the colon at the end). For example:
<!-- @@Field: <field-name> --> |
The field name (indicated as <field-name>
above) should be specified as it appears in the "history" tab, except for system fields for which the name should be as listed here.
You can naturally include the real description of the custom field as well. For example:
This field represents the date and time of the Resolution of this issue. <!-- @@Field: summary --> |
You can also specify a date/time format for the value of the Calculated Date/Time field. In the Description field, add the name of the date/time format using the following syntax:
<!-- @@Format: <format_name> --> |
where <format_name>
is one of the constants found here: https://developer.atlassian.com/static/javadoc/jira/reference/com/atlassian/jira/datetime/DateTimeStyle.html
A user field that returns the author of the last change made on a field.
The field whose last modification author should be returned must be indicated in the field description inside an html comment (so that it remains invisible when showing the field description), preceded by the following keyword: @@Field: (note the colon at the end). For example:
<!-- @@Field: <field-name> --> |
The field name (indicated as <field-name>
above) should be specified as it appears in the "history" tab, except for system fields for which the name should be as listed here.
You can naturally include the real description of the custom field as well. For example:
This field represents the date and time of the Resolution of this issue. <!-- @@Field: summary --> |
The currentUserPropertyAsList function can be used in a JQL query in an "in" or "not in" condition. It takes one parameter: the name of a user property.
When running the search query, the function will grab the value of the user property and treat it as a comma-separated list of values.
This function is especially useful for building shared filters (and dashboards). You can, for example, create a standard filter that lists open issues for the current user's preferred projects, which you'll store in a user property:
resolution = Unresolved AND project in currentUserPropertyAsList("myProjects") |