Custom Events


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 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.


Creating a Custom Event

  1. Open the admin panel > Custom Events tab. While the tab has no custom events it shows the note “No custom events yet”.
  2. Click Create at the top right of the tab (or Edit in the row of an existing event)
  3. 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.
  4. 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 - 10179 says 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:

  1. Go to Jira Settings > Issues > Custom fields
  2. Find the field, click … (more actions) > Contexts and default value
  3. 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 Stopwatch

After creating a Custom Event, use it as a trigger in a Stopwatch field setting or panel:

  1. Open a Stopwatch field setting or panel in the admin panel, tab Events
  2. In the event slots (Start, Pause, Stop, or Restart), click Add event
  3. Select Custom event (CUSTOM_EVENT) as the trigger type
  4. Select your Custom Event from the dropdown
  5. Save

The stopwatch will now react when the custom event fires.

See Event triggers reference for more details on how triggers work.

Custom events of the Connect app move together with its settings (see Moving from the Connect app): they appear on the Custom Events tab, and the events of the moved settings point at them.

Health Check lists events that refer to a deleted custom event.


Examples

Example 1: Start stopwatch when priority changes to Highest

  1. Create Custom Event:
    • Name: “Priority to Highest”
    • Field: Priority
    • Action: CHANGE_TO
    • Value To: Highest
  2. In Stopwatch field settings, add to Start Events:
    • Trigger: CUSTOM_EVENT
    • Custom Event: “Priority to Highest”

Example 2: Pause stopwatch when resolution is set to “Won’t Do”

  1. Create Custom Event:
    • Name: “Resolution Won’t Do”
    • Field: Resolution
    • Action: CHANGE_TO
    • Value To: Won’t Do
  2. In Stopwatch field settings, add to Pause Events:
    • Trigger: CUSTOM_EVENT
    • Custom Event: “Resolution Won’t Do”

Example 3: Restart stopwatch when assignee changes

  1. Create Custom Event:
    • Name: “Assignee changed”
    • Field: Assignee
    • Action: CHANGE
  2. In Stopwatch field settings, add to Restart Events:
    • Trigger: CUSTOM_EVENT
    • Custom Event: “Assignee changed”

Tips

  • Custom Events vs built-in triggers: use built-in triggers for common scenarios (STATUS_TO, RESOLUTION_SET, etc.). Use Custom Events when you need to match specific values or transitions that built-in triggers cannot express.
  • Reusable: one Custom Event can be used by multiple Stopwatch fields and panels.
  • Take custom field values from history: if an event on a custom field never fires, open the issue changelog and compare what Jira recorded there with what you typed into ID and Display name - see Custom fields.
  • Test carefully: Custom Events match against the issue changelog. After creating, check an issue in the Preview of the field setting, then recalculate existing issues when the Configuration changed window offers it.