8.1 Jira Events, System Events & Notification Schemes

8.1 Jira Events, System Events & Notification Schemes

Quick Summary: In Jira Cloud, notifications are powered by an event-driven subsystem. Whenever a user creates an issue, edits a field, adds a comment, or executes a workflow transition, Jira fires an Event. A project's Notification Scheme intercepts these events and routes email alerts to configured recipient types. Understanding the distinction between built-in system events and custom events, the mechanics of workflow post functions, and scheme association is essential for enterprise Jira administration.

---

Jira Cloud Event-Driven Notification Architecture

Atlassian Cloud utilizes an asynchronous event bus to handle system and issue lifecycle changes. When a state change occurs in Jira, the application does not directly dispatch an email to hardcoded users. Instead, it publishes an event record containing the issue context, the initiating actor, and the updated field metadata.

The notification lifecycle follows four sequential stages:

1. Event Trigger: An action occurs via the web interface, mobile app, REST API, or workflow transition (e.g., a developer transitions an issue to In Review).
2. Event Bus Publication: Jira publishes a specific event (such as Issue Updated or a custom Ready for Code Review event).
3. Notification Scheme Evaluation: Jira consults the Notification Scheme associated with the issue's project, identifying all recipient types subscribed to that event.
4. Security & Deduplication Pipeline: Jira checks issue-level security and project browse permissions, filters out unauthorized accounts, resolves deduplicated recipient sets, and submits outgoing messages to the email batching queue.

+-------------------------------------------------------------------------+
|                   JIRA EVENT & NOTIFICATION PIPELINE                    |
+-------------------------------------------------------------------------+
|                                                                         |
|  [ User Action / Workflow Transition ]                                  |
|                     |                                                   |
|                     v                                                   |
|  [ Jira Event Bus: Fired Event (System or Custom) ]                     |
|                     |                                                   |
|                     v                                                   |
|  [ Project Notification Scheme Lookup ]                                 |
|     - Maps Event -> Recipient Definitions (Assignee, Roles, Groups)     |
|                     |                                                   |
|                     v                                                   |
|  [ Access & Permission Filtering ]                                      |
|     - Verify 'Browse Projects' Permission                               |
|     - Verify Issue Security Level Containment                           |
|                     |                                                   |
|                     v                                                   |
|  [ Deduplication & Batching Engine ]                                    |
|     - Deduplicate overlapping recipient criteria                        |
|     - Batch updates (3-min idle, 10-min max; mentions go now)           |
|                     |                                                   |
|                     v                                                   |
|  [ Outgoing Mail Service (Atlassian SMTP / Custom SPF & DKIM) ]         |
+-------------------------------------------------------------------------+

---

System Events in Jira Cloud

Jira Cloud ships with a fixed set of system events. Atlassian's rules for them: system events can't be added or deleted, but they can be made inactive (an event is active when a notification scheme or a workflow post function uses it). The built-in system events are:

Some events are fired by Jira internally (Issue Updated, Issue Moved). Others, such as Issue Resolved or a custom event, are fired only because a workflow transition is configured to fire them.

The Role of the Generic Event

When an administrator creates a new workflow transition, Jira sets it to fire the Generic Event by default. If the administrator does not explicitly change this to a specific event (or a custom event), any notification sent as a result of that transition will use the Generic Event mapping in the project's Notification Scheme. If the Generic Event has no recipients configured in the Notification Scheme, no email will be sent.

---

Custom Events: Purpose, Creation & Lifecycle

While system events cover standard CRUD operations, complex business processes require targeted notifications for specific workflow milestones—such as Escalated to Tier 3, Awaiting Legal Approval, or QA Build Ready. This is achieved through Custom Events.

Creating a Custom Event in Jira Cloud

Custom events are defined globally across the Jira Cloud site:

1. Go to Settings > System, then Advanced > Events.
2. Scroll to the Add New Event form at the bottom of the page.
3. Enter the required parameters:
   • Name: A descriptive label (e.g., Issue Escalated to Executive Team).
   • Description: Context detailing when and where this event is fired.
   • Template: The email template the event uses. Atlassian's custom-event procedure uses the Generic event template, which looks much like the Issue Updated email.
4. Click Add. The new event starts out inactive, because no notification scheme or workflow uses it yet.

+-------------------------------------------------------------------------+
|                          ADD NEW EVENT INTERFACE                        |
+-------------------------------------------------------------------------+
|  Name:        [ Issue Escalated to Executive Team                    ]  |
|  Description: [ Fired when an incident transitions to Sev-1 Escalated]  |
|  Template:    [ Issue Updated                                      v ]  |
|               | Issue Created                                      |    |
|               | Issue Updated                                      |    |
|               | Issue Commented                                    |    |
|               | Generic Event                                      |    |
|               +----------------------------------------------------+    |
|                                                                         |
|  [ Add Event ]                                                          |
+-------------------------------------------------------------------------+

Event Templates Explained

Every custom event must be linked to an underlying system event template. In Jira Cloud, the template controls the visual presentation and subject formatting of outgoing emails:

• Issue Created Template: Formats the email as a newly spawned item, emphasizing creation metadata, project key, and initial description.
• Issue Updated Template: Highlights field-level diffs, changes between previous and new values, and status movements.
• Generic Event Template: Provides a standard, neutral notification envelope displaying issue attributes and comments.

Custom Event Deletion Rules & Constraints

An event is active when it's associated with at least one notification scheme or workflow post function, and inactive otherwise. Only inactive custom events can be deleted. To retire a custom event:

1. Remove it from every workflow transition that fires it (change those transitions back to the Generic Event or another event), and update the workflows.
2. Remove its entries from every notification scheme that references it.
3. Return to Settings > System > Advanced > Events. Once the event shows as inactive, delete it.

System events can never be deleted, although they can be inactive. Also remember that an active status doesn't mean an event will fire. A custom event fires only when a transition in an active workflow is configured to fire it.

---

Firing Events from Workflow Transitions

Custom events can't be fired from ordinary edit or assign actions. They're fired by workflow transitions in company-managed projects. Atlassian's procedure has three parts:

1. Add the custom event (Settings > System > Advanced > Events).
2. Map recipients in the notification scheme: open the scheme (Settings > Issues > Notification schemes), find the custom event at the bottom of the list, and add recipients.
3. Configure the transition to fire it: edit the workflow, select the transition, and choose the custom event in the transition's Event setting (in the legacy editor, edit the "Fire a … event" post function). Select Update workflow to publish. Every project that uses the workflow now sends the email on that transition.

+-------------------------------------------------------------------------+
|             WORKFLOW TRANSITION POST FUNCTION CONFIGURATION             |
+-------------------------------------------------------------------------+
|  Transition: Escalate (from [In Progress] to [Escalated])               |
|                                                                         |
|  Standard Post Functions Execution Sequence:                            |
|  1. Set issue status to the linked status of destination node.          |
|  2. Update Issue Field: Priority = Critical.                            |
|  3. Update Issue Field: Escalation Date = now.                          |
|  4. Update change history and store the issue.                          |
|  5. Fire an event that can be processed by the listeners:               |
|     --> [ Issue Escalated to Executive Team ]                           |
+-------------------------------------------------------------------------+

The Critical Importance of Post Function Execution Order

A frequent source of exam scenario questions involves the execution sequence of workflow transition post functions. In Jira workflows, post functions execute sequentially from top to bottom:

Exam Trap — Stale Notification Data: In an ordered post-function list, if Fire an event that can be processed by the listeners is positioned before an Update Issue Field post function (or before setting the Resolution field), the notification listener processes the issue in its pre-update state. Recipient emails will display the old field values or omit the newly assigned resolution. To ensure outgoing emails reflect accurate, committed data, the event-firing post function should always be placed at or near the very end of the post function execution chain, immediately following the step that stores the issue revision to the database.

Notification Schemes in Company-Managed Projects

A Notification Scheme is a centralized, reusable administrative scheme that dictates which individuals, groups, or roles receive email notifications when specific events fire within Company-Managed Projects (CMP).

Navigating and Structuring Notification Schemes

Administrators manage notification schemes via Cog > Jira settings > Issues > Notification schemes.

• Each scheme contains an itemized table listing all active events (System Events and site-wide Custom Events).
• For each event, administrators define one or more Notification Types / Recipients (such as Current Assignee, Reporter, Project Lead, Project Role, or User Custom Field Value).
• A single event can have multiple recipient rules attached. For example, the Issue Created event might be mapped to Current Assignee, Project Role (Developers), and User Custom Field Value (QA Lead).

+-------------------------------------------------------------------------+
|              NOTIFICATION SCHEME CONFIGURATION MATRIX                   |
+-------------------------------------------------------------------------+
|  Event Name           | Notified Recipients                             |
| :-------------------- | :---------------------------------------------- |
|  Issue Created        | Current Assignee, Reporter, Project Lead        |
|  Issue Updated        | Current Assignee, Reporter, All Watchers        |
|  Issue Assigned       | Current Assignee                                |
|  Issue Resolved       | Reporter, All Watchers                          |
|  Generic Event        | Project Role (Stakeholders)                     |
|  Incident Escalated   | Project Role (Incident Commanders),             |
|  (Custom Event)       | User Custom Field Value (Executive Sponsor)     |
+-------------------------------------------------------------------------+

The Default Notification Scheme

Jira Cloud provides a system-generated Default Notification Scheme with every new instance:

• When a new company-managed project is created, Jira automatically associates it with the Default Notification Scheme unless a project template specifies a different scheme.
• In the Default Notification Scheme, standard events (Issue Created, Issue Updated, Issue Assigned, Issue Commented, etc.) are mapped to Current Assignee, Reporter, and All Watchers.
• Editing the Default Notification Scheme alters notification behavior across all projects that remain linked to it.

Associating a Scheme with a Project

To change or assign a notification scheme for a company-managed project (select None to stop the project sending scheme-based emails):

1. Open the target project and select Project settings from the left-hand sidebar.
2. Navigate to Notifications.
3. In the top-right corner, open the Actions dropdown menu and select Use a different scheme.
4. Select the desired scheme from the list of available notification schemes.
5. Click Associate.

+-------------------------------------------------------------------------+
|               ASSOCIATING NOTIFICATION SCHEME TO PROJECT                |
+-------------------------------------------------------------------------+
|  Project Settings > Notifications > Actions > Use a different scheme   |
|                                                                         |
|  Available Schemes:                                                     |
|  ( ) Default Notification Scheme (Associated with 14 projects)          |
|  (o) High-Security Incident Notification Scheme (Associated with 2 proj)|
|  ( ) Software Development Notification Scheme (Associated with 8 proj)  |
|                                                                         |
|  [ Associate ]  [ Cancel ]                                              |
+-------------------------------------------------------------------------+

Modifying Shared Notification Schemes: Governance Best Practice

In enterprise environments, multiple projects frequently share a single Notification Scheme. A common administrative error occurs when a Project Administrator requests a change—for example, removing All Watchers from the Issue Updated event to decrease email noise:

• If a Jira Administrator navigates to Issues > Notification schemes and removes All Watchers directly from that shared scheme, the change instantly applies to every single project linked to that scheme.
• Recommended Administrative Workflow:
  1. Check how many projects are associated with the target scheme.
  2. If the scheme is shared and only one project requires customized routing, click Copy next to the scheme in the global Notification Schemes repository.
  3. Rename the copy (e.g., Core Banking Project Notification Scheme).
  4. Edit the event-recipient mappings in the newly created scheme.
  5. Navigate to the requesting project's Project settings > Notifications, select Actions > Use a different scheme, and switch the project to the new scheme.
  6. This isolates the change without disrupting other organizational teams.

Company-Managed vs. Team-Managed Notification Architecture

A clear distinction exists between project types in Jira Cloud:

In team-managed projects, notifications are set per project in Project settings > Notifications. A notification scheme can't be applied to a team-managed project. Section 8.3 covers team-managed notifications in detail.