Define notifications for company-managed projects using schemes
10 min
Advanced
By the end of this lesson, you’ll be able to:
- Create a notification scheme
- Add an event recipient to a notification scheme
- Use the notification helper
What is a notification scheme?
Jira sends email notifications to users for various activities in Jira.
👉 For example:
- Users can create saved filters, and then add filter subscriptions based on the saved filter. Jira sends emails with the filter results, as either personal or group subscriptions.Â
- Users can also share work and filters from within Jira, which sends an email to recipients.
- Users can @ mention others in the work item description and comments.
- Admins can use the Send Email function.
- Automation rules can send notifications.
The most common type of notification relates to events. These notifications exist at the project level. Jira admins configure them for company-managed projects. Team-managed project admins configure notifications for their individual project and can’t use schemes.
Users can configure some of their own notifications through their Jira settings. Their preferences override notification schemes.
Notification schemes associate events with specific email recipients.
👉 For example: The Work item assigned event notifies users when a work item's Assignee value changes.
Every notification scheme lists all system events, related to work activity, as well as any custom events you add. Jira admins can add custom events for specific use cases.
👉 For example: You could add custom events for when a work item is ready for peer review, when a work item requires approval, or when a work item is waiting for customer input.
To create a custom event:
- In the upper-right corner of Jira, select Settings (represented by a gear icon).
- Under Jira admin settings, select System.
- In the sidebar, under Advanced, select Events.
- At the bottom of the page, enter your details and select Add.
For each event in a notification scheme, Jira admins select a recipient. Like other schemes, you can add project roles, groups, individual users, and other entities as recipients.
👉 For example: In the HR Notification scheme, the Work Item Created event will send an email to everyone who is listed in the Managers project role of that project. Additionally, the Work Item Deleted event will notify all users in the jira-administrators group.
We recommend you use project roles as much as possible when configuring schemes. They’re more flexible as project admins can add users to roles for their projects.
Configure a notification scheme
Create a notification scheme
Notification schemes apply to all work types in a project. You can use automation rules to send notifications based on specific work types. However, make sure to only send notifications for events that users truly need to know about as they happen. You can use dashboards and reports to share information that isn’t time sensitive.
To create a notification scheme:
- In the upper-right corner of Jira, select Settings (represented by a gear icon).
- Under Jira admin settings, select Work items.
- In the sidebar, under Work item attributes, select Notification schemes.
- Select Add notification scheme.
- Name your scheme and add a detailed description so Jira admins know when to use it.
- Select Add.
- Next to any event, select Add to add a recipient. If you don’t want to send a notification for that event, just leave the recipients empty.
- Select an entity to add as a recipient, then select Add.
👇 Watch this video to learn how to configure a notification scheme.
Associate a notification scheme with a project
To apply the notification scheme, you need to associate it with one or multiple projects. Only Jira admins can associate notification schemes with projects.
When you first create a company-managed project, it will use the default notification scheme. In that scheme, all events send to the Current Assignee, Reporter, and All watchers, by default. Jira admins can configure this scheme as needed.
You can also change which scheme a project uses after you create the project.
To associate a notification scheme with a project:
- Open the project in Jira.
- In the sidebar, next to the project name, select More actions (represented by ···), then Project settings.
- In the project settings sidebar, under Notifications, select Settings.
- In the upper-right, select Actions, then select Use a different scheme.
- Select your scheme, then select Associate.
👇 Watch this video to learn how to associate a notification scheme with a project.
Troubleshoot notifications
There are multiple reasons why emails may not send as expected. Ask these questions to guide your investigation:
- Is everyone else receiving emails? If not, this might be a work item across your Jira site, not with a specific notification scheme.
- Is the user receiving emails from the relevant project? If not, check the project’s notification scheme.
- What notifications was the user expecting? You can use the Notification Helper on a notification scheme's admin page when you know the specific event and recipient.
- Does the user have the right permissions? Check that they can see the correct work in the project’s permission scheme.
- Did the user opt out of notifications in their personal settings? These settings override notification schemes.
- Is the workflow firing the correct event? If not, the problem might be in the workflow’s configuration.
Let’s explore an example!
Jane, a member of the APEX project, tells Shohei, a Jira admin, that she isn’t receiving notifications when work items are resolved.
During Shohei’s troubleshooting, he discovers that:
- Jane is in the Managers project role.
- The Managers project role is a recipient for the Work Item Resolved event.
- The Managers project role has the correct permissions in the permissions scheme.
- The project does not have work item-level security.Â
- Jane hasn't disabled any notifications in personal settings.
Shohei realizes that the workflow configuration is likely the work item. He checks which event fires when users resolve a work item. Instead of firing the Work Item Resolved or Work Item Closed events, the workflow fires the Generic event.
Jane is not a recipient for that event in the notification scheme, so she isn’t receiving notifications. Shohei can either:
- Update the workflow to fire the Work Item Resolved event when users resolve a work item.
- Update the notification scheme to include the Managers role as a recipient for the Generic event.
How was this lesson?
next lesson
What are workflows in Jira?
- Represent how your team works
- Explore default workflows
- Explore simplified workflows
- Compare workflows in company-managed and team-managed projects