- What are Custom Events?
- Creating a Custom Event
- Actions
- Supported fields
- Using Custom Events in other apps
What are Custom Events?
Custom Events are user-defined rules that fire when a specific field value changes in a particular way. They extend the built-in event triggers by letting you match precise value transitions.
For example:
- “Priority changed to Highest”
- “Resolution changed from Fixed to Won’t Fix”
- “Custom field ‘Region’ set for the first time”
Custom Events are created on the Custom Events tab of the admin panel and then used as start, pause, stop or restart events of Stopwatch and Timer fields and panels (trigger type CUSTOM_EVENT). The tab is in every app of the family: Time in Status, Timer, Stopwatch and Time Between Dates.
Time Between Dates fields do not use events: they are calculated from two dates of the issue. The Custom Events tab is still there, the same as in the other apps of the family.
Creating a Custom Event
- Open the admin panel > Custom Events tab. While the tab has no custom events it shows the note “No custom events yet”.
- Click Create at the top right of the tab (or Edit in the row of an existing event)
-
Fill in the configuration:
Field Description Name Name shown in event lists (e.g., “Priority changed to High”). Required, unique, up to 150 characters, without \ / > < & %.Description Optional; shown under the name in event lists. Field The field to monitor: a system field (Status, Priority, Issue Type, Resolution, Assignee, Reporter) or any custom field. Default: Status. Action The type of change to detect (see Actions below). Value From The previous value. Shown for CHANGE_FROM and CHANGE_FROM_TO only. Value To The new value. Shown for CHANGE_TO and CHANGE_FROM_TO only. The value inputs appear only for those three actions. SET, REMOVE, CHANGE and FIRST_SET match the change itself, so the form shows no value inputs for them.
How a value is entered depends on the field:
- Status, Priority, Issue Type, Resolution - pick the value from a dropdown.
- Assignee, Reporter - no dropdown. Type the value into the same two inputs custom fields use - ID (the Atlassian account ID) and Display name - see System fields.
- Custom fields - two inputs, ID and Display name - see Custom fields for what to type into them.
- Click Save to store the event, or Close to leave the form without saving. A form with unsaved changes asks “Discard unsaved changes?” first - see Forms and dialogs.
When you change a custom event that is in use, the app offers to recalculate the fields that use it - see Configuration changed.
Actions
The Action list shows the names below; the code in brackets is how this page refers to the action. Default: Field changed TO value.
| Action in the form | Fires when | Requires |
|---|---|---|
Field changed TO value (CHANGE_TO) |
The field gets the “to” value | Value To |
Field changed FROM value (CHANGE_FROM) |
The field leaves the “from” value | Value From |
Field changed FROM value TO value (CHANGE_FROM_TO) |
The field changes from one value to another | Value From, Value To |
Field value set (from empty) (SET) |
An empty field gets a value | - |
Field value removed (to empty) (REMOVE) |
The field becomes empty | - |
Field changed (any change) (CHANGE) |
Any change of the field | - |
Field value set for the first time (FIRST_SET) |
The field gets a value for the first time | - |
An issue created with a value fires the actions “changed TO”, “set” and “set for the first time” at creation.
SET and REMOVE fire on the transition between “empty” and “not empty” regardless of the value involved, so they take no Value To or Value From. Use CHANGE_TO or CHANGE_FROM when the specific value matters.
Supported fields
System fields
- Status - issue status
- Priority - issue priority
- Issue Type - issue type
- Resolution - issue resolution
- Assignee - issue assignee
- Reporter - issue reporter
Status, Priority, Issue Type and Resolution offer a dropdown: the Value From and Value To inputs list the values available on your site (status names, priority names, and so on).
Assignee and Reporter have no dropdown. Their values are entered exactly like custom field values - each value slot has two inputs, ID and Display name:
- ID - the user’s Atlassian account ID, for example
5b10a2844c20165700ede21g. Open the user’s profile in Jira and take the ID from the page URL, which ends with/jira/people/<accountId>. - Display name - the user’s display name as Jira recorded it in the changelog, for example
Jane Cooper.
Filling one of the two is enough, and the same OR rule applies as for custom fields - see Custom fields. ID is the durable choice: the account ID does not change when the user is renamed, while a value matched by display name stops firing after a rename.
Custom fields
Any custom field that appears in the issue changelog can be used. Custom field values are not offered as a dropdown - you type them in, and every value slot (Value From, Value To) has two inputs: ID and Display name.
What the app compares
The app does not look at the current value of a field. It replays the issue changelog (the issue history) and compares your configuration with the recorded change. Jira records each change in two forms, and each form is matched by its own input:
- Internal value - the identifier Jira stores for the value. For option-based fields this is the numeric option ID, for example
10179. This is what the ID input is compared with. - Display string - the value as it is shown in the issue, for example
Active. This is what the Display name input is compared with.
Option-based fields (single select, multi select, radio buttons, checkboxes, cascading select) have both forms. Text, number, and URL fields have no internal identifier - Jira records the display string only.
So ID takes the option ID, and Display name takes the label you see in Jira. Typing the label into ID will not match anything.
Filling one input is enough
- Fill ID, Display name, or both - one filled input is enough for the event to work.
- An empty input takes no part in the comparison.
- If both are filled, the event fires when at least one of them matches (OR), not when both match.
Which one to use:
- Display name is the easier choice: it is the label you already see in the issue, and it makes the event readable in the events list. Its weak spot is renaming - if someone renames the option, changes recorded under the new label stop matching and the event has to be updated.
- ID is the durable choice: the option ID does not change when the option is renamed, so the event keeps working. The trade-off is readability -
10179says nothing about the value, and you have to look it up first.
For text, number, and URL fields there is no internal identifier: leave ID empty and put the exact value into Display name. The comparison is exact, so copy the value as Jira recorded it rather than retyping it from memory.
Finding the option ID
For an option-based custom field:
- Go to Jira Settings > Issues > Custom fields
- Find the field, click … (more actions) > Contexts and default value
- Open the context that holds the options and start editing the option you need - the numeric option ID appears in the page URL
You can also read both forms straight from the data the app matches against - the issue changelog:
https://<your-site>.atlassian.net/rest/api/3/issue/<issue-key>/changelog
Each history item shows from / to (internal values, matched by ID) and fromString / toString (display strings, matched by Display name).
Example: select field “Activity State”
The custom field Activity State is a single select with an option Active whose option ID is 10179. To fire an event when the field changes to Active, create an event with Field = Activity State and Action = CHANGE_TO, then fill Value To in either of these ways:
| Configuration | Value To - ID | Value To - Display name |
|---|---|---|
| By display name | (empty) | Active |
| By option ID | 10179 |
(empty) |
Both fire on the same change. Filling both inputs (10179 in ID and Active in Display name) is also valid - the event then fires when either form matches.
Using Custom Events in other apps
Time Between Dates fields have no events, so the custom events of this app are not used by its fields. In the Time in Status, Timer and Stopwatch apps a custom event is used as an event of Stopwatch and Timer fields and panels.
Health Check lists events that refer to a deleted custom event.

