Field Reference - Calculated Fields (Forge)

JBCF Forge registers 32 Jira custom field types: 31 read-only calculated fields and the interactive ToDo List field. Each of them is a standard Jira custom field - searchable, sortable, and exportable.

The tables below cover the six groups of calculated fields - Comments (12), Status history (7), Links (4), Project (2), Sort (5), and Jira Service Management SLA (1) - followed by the ToDo List field. The field-type list in Jira’s Create custom field dialog is always the authoritative set for the version you have installed.

The Event triggers column lists the Jira events that cause the field to recalculate. Calculations are performed inside the Forge runtime and the result is written back to Jira as the field value.

Calculated fields are read-only: the app works out the value from the issue and writes it into the field. When the data a field needs is not there (for example, no comments yet), the field is empty, and the issue shows it as None - text, number, date and user fields alike. Counters are the exception: an issue with no comments, links or sub-tasks shows 0. Writing a calculated value does not add an entry to the issue history.

Ten fields return a Jira user, and their data type is user: the field value holds the user’s accountId, and Jira itself shows the user with their avatar. You search them like any user field - for example, = currentUser() works. Seven of them hold one user; cf-commented-users, cf-who-was-assignee, and cf-component-leads hold a list of users, each listed once.


Comment fields

Twelve fields derived from the issue’s comment thread.

Field Description Data type Event triggers
cf-number-of-comments Number of comments on the issue. number comment added, edited, deleted
cf-text-last-comment Text of the last comment, cut to 255 characters. string comment added, edited, deleted
cf-commented-users Users who have commented on the issue, each listed once. user comment added, edited, deleted
cf-user-last-commented The user who left the last comment. user comment added, edited, deleted
cf-date-last-comment Date/time when the last comment was posted. datetime comment added, edited, deleted
cf-is-last-comment-assignee Yes if the last commenter is the current assignee, No otherwise. string comment added, edited, deleted; assignee changed
cf-is-last-comment-reporter Yes if the last commenter is the issue reporter, No otherwise. string comment added, edited, deleted; reporter changed
cf-text-first-comment Text of the first comment, cut to 255 characters. string comment added, edited, deleted
cf-first-comment-author The user who left the first comment. user comment added, edited, deleted
cf-date-first-comment Date/time when the first comment was posted. datetime comment added, edited, deleted
cf-is-first-comment-assignee Yes if the first commenter is the current assignee, No otherwise. string comment added, edited, deleted; assignee changed
cf-is-first-comment-reporter Yes if the first commenter is the issue reporter, No otherwise. string comment added, edited, deleted; reporter changed

Last comment and First comment (cf-text-last-comment, cf-text-first-comment) hold at most 255 characters, the limit of a Forge string field, counted in UTF-16 code units. A longer comment is cut and ends with ….

The four Yes/No fields hold the text Yes or No and compare the commenter with the current assignee or reporter. Besides comment events, they are recalculated when the person they compare against changes: changing the assignee recalculates Is author of last comment assignee and Is author of first comment assignee, changing the reporter recalculates Is author of last comment reporter and Is author of first comment reporter. An issue without an assignee (or without a reporter) answers No; the field is empty only when the issue has no comments (or the comment’s author is unknown).

Only comments that everyone who sees the issue can see are used. A comment restricted to a project role or a group, and an internal comment in Jira Service Management, is skipped: its text, author and date never appear in a field. For example, Last comment shows the newest comment that is not restricted or internal, and an issue whose comments are all restricted or internal counts as having no comments. Number of comments is the exception: it counts every comment on the issue, as Jira reports it.

If Jira does not return the comments when the app asks for them, the comment fields keep their previous value instead of being cleared.


Searching comment fields

The comment fields are regular Jira custom fields, so you search them with JQL. JQL refers to a field by the name it was given when it was created; the examples use the default names below - substitute the name of your own field.

Field name in the examples Field
Last comment cf-text-last-comment
Is author of last comment assignee cf-is-last-comment-assignee
Date of last comment cf-date-last-comment
User last commented cf-user-last-commented

Text fields - Last comment, First comment, the four Yes/No fields, Previous status and the sort fields - are matched on the whole value: =, in and is EMPTY work; searching for a word with ~ does not find them. For example, issues that have no comment yet, and issues whose last comment is from the assignee:

"Last comment" is EMPTY
"Is author of last comment assignee" = "Yes"

Issues commented on in the last seven days:

"Date of last comment" >= -7d

Issues where you, or one of the listed users, left the last comment. User last commented is a user field, so user functions and lists work as in any user field:

"User last commented" = currentUser()
"User last commented" in (currentUser(), membersOf("support-team"))

Changelog fields

The status history group - 7 fields - is derived from the issue’s changelog (status, assignee, resolution history).

Field Description Data type Event triggers
cf-previous-status The status the issue was in before its current status. string status changed
cf-previous-assignee The user assigned to the issue before the current assignee. user assignee changed
cf-last-change-status-author The user who triggered the last status change. user status changed
cf-user-resolver Who last changed the Resolution field (set it or cleared it). user resolution set/changed
cf-user-last-updater The last person or other app (for example, Automation) who updated the issue. The app’s own entries in the history - a ToDo List write from the panel or from a template - are skipped; if every entry was made by the app, the field is empty. user any issue update
cf-who-was-assignee Users who have been assigned to the issue, each listed once. user assignee changed
cf-date-of-last-transition Date/time the issue last moved into the status chosen in the field configuration, or into any status. datetime status changed

Date of last transition (cf-date-of-last-transition) is configured in the field’s context: in Jira, go to Custom fields, open the field, then Contexts → Edit configuration, and under Report the last transition into pick a status or Any status — the last transition of any kind. Until a status is chosen, the field is empty on every issue (“Nothing is chosen yet, so the field is empty on every issue.”), and Save stays unavailable until you choose. With Any status, an issue that has never been transitioned shows its creation date. Renaming a status does not change the value: the field compares statuses by id, not by name. A status that was deleted from the site stays selected and is shown as “Status <id> (no longer on this site)”. See also Context configuration.


Issue fields

Four numeric counters derived from the issue’s links and subtasks.

Field Description Data type Event triggers
cf-number-of-links Total number of issue links on the issue. number link created, deleted
cf-number-of-subtasks Number of subtasks under the issue. number subtask created, deleted
cf-number-of-inward-links Number of inward-direction issue links (issues that link to this one). number link created, deleted
cf-number-of-outward-links Number of outward-direction issue links (issues this one links to). number link created, deleted

Project fields

Two fields derived from the issue’s project and component metadata.

Field Description Data type Event triggers
cf-component-leads Users marked as component lead on the issue’s components, each listed once. user components changed
cf-user-project-lead The project lead of the issue’s project. user issue events for the issue

Jira does not emit an event when a project lead or a component lead is changed in project administration. These two fields therefore keep their stored value until the issue is recalculated - on the issue’s next event or through a bulk recalculation.


Sort fields

Five composite sort keys for hierarchical ordering in lists, filters, and Issue Navigator columns. The fields are strings shaped for lexical sort, so plain ascending or descending sort in Jira gives you the hierarchy you expect.

Field Description Data type Event triggers
cf-sort-by-parent-asc Sort key that groups subtasks under their parent, parent first, subtasks ascending by key. string parent changed, key assigned
cf-sort-by-parent-desc Sort key that groups subtasks under their parent, parent first, subtasks descending by key. string parent changed, key assigned
cf-sort-by-epic-asc Sort key that groups issues under their parent epic in ascending epic-key order. string parent epic changed, key assigned
cf-sort-by-epic-desc Sort key that groups issues under their parent epic in descending epic-key order. string parent epic changed, key assigned
cf-sort-by-epic-rank Composite sort key combining the issue’s epic and its rank inside that epic - good for backlog-style ordering across the whole project. string parent epic changed, rank changed

Example: keeping subtasks with their parent

The value of cf-sort-by-parent-asc is PARENT-KEY:ISSUE-KEY for an issue with a parent, and the issue’s own key for an issue without one. In a JQL filter view sorted by cf-sort-by-parent-asc ASC, an issue navigator that would normally interleave parent and subtask keys instead groups every subtask immediately under its parent:

PROJ-100            (parent)
PROJ-100:PROJ-101   (subtask of PROJ-100)
PROJ-100:PROJ-104   (subtask of PROJ-100)
PROJ-102            (parent)
PROJ-102:PROJ-103   (subtask of PROJ-102)

cf-sort-by-epic-rank adds the parent epic’s rank into the key, which is what you usually want when ordering a delivery backlog: epics in their rank order, child stories in their rank order under each epic.


Jira Service Management SLA fields

One field derived from a Jira Service Management SLA metric on the issue.

Field Description Data type Event triggers
cf-sla-breach-time SLA breach time - the moment the goal of the current cycle of a JSM SLA metric will be breached. datetime issue events for the issue

You pick the SLA metric in the field’s context configuration (Report the breach time of). The field is empty:

  • until a metric is selected;
  • while the current cycle is paused;
  • after the cycle has completed;
  • on issues that do not have that SLA.

If the site has no SLA fields yet, the form says so: an SLA appears in the list once a service project defines one. An SLA field that was deleted from the site stays selected and is shown as “SLA field <id> (no longer on this site)”. If the SLA cannot be read when the value is calculated, the field keeps its previous value.

The value is recalculated on the issue’s events.


Context configuration

Two calculated fields take a configuration in the field’s context: Date of last transition (which status to track) and SLA breach time (which SLA metric to report). All other calculated fields work without configuration.

A context configuration applies only within its own context. A configuration set on a project context is not applied to issues of other projects: there the field is calculated as if it had no configuration - for example, Date of last transition stays empty.


ToDo List

cf-todo-list is the one JBCF Forge field that is not calculated: it is an interactive checklist that users fill in on the issue itself. Items are stored by the app, not derived from issue state.

Field Description Data type Editable
cf-todo-list A list of items on the issue, each of which can be marked done and optionally assigned to a user. list of items yes - on the issue

What comes with the field:

  • An issue panel for working with the list on the issue view.
  • Three JQL functions for finding issues by the state of their checklist - see ToDo List in JQL.
  • A workflow validator that blocks a transition while the checklist still has unresolved mandatory items - see Workflow validator.
  • A REST API - two Forge apiRoute endpoints (GET and PUT /todo/items) that let your scripts and integrations read and replace the items of a checklist, with separate read and write scopes. See ToDo List REST API.

Each item stores the accountId of the user it is assigned to. See Security - Personal data for how that is handled.

How to use the field - its items, the view on the issue, the editor, the issue panel, and the field context settings with your own statuses - is on the ToDo List page. To prefill the field on new issues, see Checklist templates.


Field recalculation summary

  • New and updated issues are processed in near real time via Forge event triggers.
  • Historical issues are populated lazily the first time their relevant event fires, or in bulk from the app’s admin page - see Recalculation.
  • Values live only in the Jira field. The app writes each calculated value to Jira, where JQL and search index it, and keeps no copy of it. Forge KVS (encrypted at rest) holds the app’s settings, its service state, and ToDo templates.
  • ToDo List is not part of this cycle - its items are saved when a user edits them.

For the full security and storage model, see Security.