Some JIRA notifications use cases

If you check out JIRA customer requests you will find quite a few that has with notifications to do. Near the top of the list is JRA-1369 Reduce email chattiness which is the problem Smartwatch for JIRA initially aimed to solve, but there are also others. How would you solve those in Smartwatch? This post is an attempt at investigating this. Can they be solved? Do they require complicated setup or is the solution straight forward? Lets see!

Notification on file attachment(JRA-1898)

This is simply the possibility to get notified when a new attachment is made to an issue. When you make an attachment the 'Issue Updated' event will be triggered, so it is possible to get a notification on this. But if you configure this, you (and probably most other users too) will get a lot of notifications for other changes to issues too, so you might not want to do this.

With Smartwatch for JIRA you can filter notifications on modified fields, so you can say that you want notifications when 'Attachment' field is changed. Actually this is covered by the pre-defined 'Content' rule, set up like this:

Smartwatch Content rule

So, just use the Content rule for your watch and you will be notified for new attachments (and new comments, changed description etc). Or define your own rule, if you want more fields to be covered.

Allow users to watch a project (JRA-5006)

The use case here is allowing users to watch all issues in a project:

Some users however would like to receive notifications whenever anything is added or modified within a specific project. In order to set this up, currently, a new group and notification scheme needs to be created for each project, and users must be added by an administrator. Instead, there should be a watch/stop watching option available on every project summary page.

(From the description of JRA-5006)

Support for this is the big addition in SmartWatch 1.1. Only it's not in the project summary page, but in the users profile, since it is up the user to set this up. In Smartwatch each user is responsible for his own watches, while JIRA and project administrators define the rules, where you might need more knowledge about how JIRA works and how your specific JIRA setup is made.
It looks like this in the profile:

Smartwatch in the user profile

As you can see in this example I will automatically get a watch with the 'Status' rule (sends notification when status changes) for all new Tasks in SWATCH project. I will also be notified when such a task is created.

Recommended usage is to use rules that don't cause too much notifications (like 'Status' or even 'Ready') and the 'Notify on create' flag for your project autowatches. That way you can look at the issue when you get the created email and decide if you want to follow it more tightly, or if this is enough (or even if you don't need a watch on it at all, and in that case remove the watch). If you are out of office when the issue is created, your inbox will not be flooded with emails, and you can take a look at the current status when you are back.

Ability to add watchers during issue creation (JRA-5493)

This use case is about making sure that new issues are noticed by the team:

As a Project Manager I want to make sure that respective team members (including me) are informed about new issue creation and depending on an issue type are automatically added as watchers. I want this to action to become inseparable from issue creation, so that the original issue reporter does not have to inform anyone about issu creation manually. I want to be able to control the watchers' list and nominate the users.

This is also covered by the changes we made for Smartwatch 1.1. Not that you can separate different issue types too in your autowatch setup. And the result is displayed is the issue page so you can easily modify the watcher list, add and remove watchers and modify the rules:

Watchers in the issue page

Rethinking JIRA watches

When your project grows beyond just a small project group you will soon se the need to be notified when issues change, even more if your project is international, with team members in different locations and perhaps even different time zones.

JIRA can help you with this. You can easily set up Jira to send you email when issues change, in fact Jira default setup probably means you will get a lot of emails.

Notifications part 1 : watchers

JIRA notification feature really has two parts. The first part, watchers is visible to everyone in the issue page:

If you are watching the issue there will be a link that says 'Stop watching this issue'  like in this screen dump, if you are not the link will say 'Watch this issue' . Any case it will work as expected and turn your watching on or off. 

There is also a little badge that shows current number of watchers.  If you click it you will eventually get a little popup where you can add or remove watchers, yourself or another user.

The watch is an on/off switch. You cannot select what changes to the issue you want to watch. Most likely you will get a lot of emails when you watch an issue. 

And if you think you are getting too many emails and try clicking 'Stop watching this issue' you might still be getting those emails That's because of the second part

Notifications part 2 : the scheme

What really determines when notification emails are sent is the notification scheme. Unlike the watchers you can't really see this in the issue screen, and a JIRA user might not even know that it is there, since they do not have access to it.

Jira comes with a default notification scheme, which looks like these two screenshots:

Notification scheme part 1

As you can see here, watchers is only part of it, you might also get emails because you reported the issue or because you are the current assignee.

A user cannot do anything about those, Even if you click 'Stop watching this issue' you will still get them.

And very likely your JIRA administrator cannot remove them either, because that would affect other users.

There is a lot more a good JIRA expert can do with the notification scheme, but since rules are the same for all issues and users you cannot really control the number of notifications sent to you.

Notification scheme part 2

The notification scheme is big, there is a lot of events you can use. If you want to you can have different rules when a comment is added and when its edited and different rules for 'Work logged', 'Work started' and 'Work stopped' for example.

But still its not fine grained enough. While there are separate events for some status changes (Created, Resolved, Closed, Reopened) there are not any events for other statuses that might be more important for your role in your workflow. When we tested those they ended up in the last one on the list, 'GenericEvent' , which is not easy for a user to know.

And there is one event for all updates, so there is no possibility to avoid updates that only affects fields you really don't want a notification for.

Conclusion

JIRA is very good at sending out email notifications, in fact many would say that it sends too many notifications. The watch/unwatch mechanism is easy to understand, but often gives you too many notifications. The notification scheme is very powerful, but hidden for most users, so they do not have control over what emails they get. Events are many, but not always easy to understand, sometimes not fine-grained enough and not available for the user to use.

This is why we developed Smartwatch for JIRA, a plugin that puts the user in control of notifications, realizing that

• users are different, they have different roles and preferences, so they want watches to work differently
• issues are different. Some needs careful monitoring and you want to follow everything, some are not so critical, but you still want to know when they are ready

Smartwatch setup guide

Smartwatch for JIRA is based on rules, that specify what changes that should trigger a notification. Before the plugin can be used you need to set up these rules. You will get a default setup, but you might want to modify the rules, add your own or perhaps deactivate some of the defaults ones.

There are also two standard JIRA settings that you might want to modify:

• you should probably not allow JIRA standard watch
• you should review and possibly modify the notification scheme used

Rules setup

You find the rules setup page under Administration /Issues / Issue attributes. The first time you open that page the plugin will generate some default data for you and it will look something like this:

The top part of the page is the rules your users can select from when they want to watch changes for issues:

• Name is the name the user will see in the dropdown list. Keep it short
• Description is a somewhat longer description of the rule
• Active determines which rules will be available in the dropdown lists. If you change a rule to be not active, it will no longer be available in the dropdowns, but watches already defined will still use the definition.

The fields All, Statuses and Fields are used when the plugin evaluates changes to issues. 

1. If the rule has the All flag all changes will trigger a notification, much like JIRA built-in watcher. The Statuses and Fields values are not relevant in this case.
2. If the Status on the issue is changed to any of the Statuses listed, the watch will be triggered, so this is what you would use to monitor status changes.
3. If any of the Fields listed are modified the watch will be triggered. 
4. You can combine Statuses and Fields in the same rule if you want to. If you do that, the rule is interpreted like a chnge to one of the listed statuses OR a change in one of the fields.

Use this page to review the deafult rules, possibly modify or deactivate them and add your own rules. Think of the different roles within your organization> what would people in different roles want to watch? Also think about hoe you use statuses. What status changes would be interesting to monitor?

Default user setup

The bottom part of the page is used for a deafult user setup. The user can override these settings in his own profile, but make sure that these fields hold reasonable default values that works for most users.

• Set on create: this watch will be added when a user creates an issue
• Set on assign: this will be added when an issue is assigned to a user, whether it is on creation, using the Assign button or by modifying the assignment and switching to another user
• Set on update: this will be added when a user modifies an issue, whether it is by modifying 

The plugin will add these watches only if the user does not already have a watch defined for the issue. So if you modify an issue, or if you have it assigned to you, and already have a watch on it, no changes will be made. Also if the issue is reassigned to someone else the plugin will not remove the watch you have, you have to do that by yourself.

Other changes in system setup

Don't allow JIRA standard watch

Even though you can use both JIRA standard watch and Smartwatch for JIRA at the same time it is confusing for your users if you do so. If you really want to watch all changes to an issue you can use the All changes rule. So it is best to turn watches OFF. You find that setting in Administration /System / General Configuration.

This will also make your Issue page cleaner, with watches only under smartwatch.

Notification scheme

When you have done all this, users still might get a lot of unwanted emails. This is because of the notification scheme feature of JIRA. You cannot see those notifications in the issue page, instead you find it under Administration /Issues / Notification schemes. 

The default setup is to notify the reporter and current assignee of practically all changes. 

If you want to use smartwatch for all notifications, you should remove these notifications. The easiest way to do this is to:

1. Create a new scheme by clicking the button 'Add notification scheme'. 
2. Give the schema a descriptive name like 'No notifications'
3. Do not add any notifications to the scheme
4. Connect your project to the new scheme under Project Administration:

Alternatively you can combine Notification schemes with Smartwatch. In that case you might want to set one or several of the rules in the default user setup to 'No watch'. But beware that users really cannot turn these notifications off.

Smartwatch users guide

Smartwatch for JIRA allows you to for each issue specify when you want to have notification. You do this by selecting a watch rule on the issue for yourself. You do this in the issue page, but you can also set up some defaults in the user profile.

Issue page

Smartwatch adds a new section to your issue page. You will find it in the right column. It contains a list of the watches defined for the issue:

For each watch you see the userid of the watcher and the rule used for the watch. The rule determines which events that will trigger a notification. So in this case erik will be notified if the content changes, admin will be notified if the status changes and axel will be notified when the issue is ready. These are all predefined rules that come with the plugin but your JIRA administrator can set up your own rules or modify or deactivate the preconfigured ones.

Add or modify your watch

The top row in the list will always contain your own userid. If you do not have a watch for this issue it will say 'No watch', otherwise you will see the name of the watch. In any case you can use JIRA inline edit to add or update the watch. Just click on the rule and you will get a dropdown list containg all currently active rules plus 'No watch'. Select the watch you want, click the OK button, and you are done.

Remove your watch

You might have guessed this: to remove your watch click on the rule and select 'No watch' in the dropdown. Click the OK button and you're done.

Add a watcher for another user

You can also add a watch for another user. Enter the userid in the input field where it says 'Add watcher', click on 'No watch' to the right of the field, select the watch and click OK. From version 1.2 you can also enter a group id or an email address, if your JIRA administrator has enabled this.

Use the popup to add watcher

Another option is to use the popup to add a watcher. You open the popup by clicking the plus sign. That opens the following dialog:

Your JIRA administrator can enable or disable the 'Group' and 'External' options. If both are disabled you will not see the 'Watcher type' radio buttons and will only be able to add users.

Profile page

Smartwatch also adds a new section to your profile page. This section defines watches that should be set up when you create or modify an issue or when it is assigned to you.

From version 1.1 it also includes a list of watches you want automatically created for you, based on project and issue type.

The new section looks like this:

• Set on create: this watch will be added to an issue you create
• Set on update: this watch will be added to an issue you modify if you do not already have a watch on it
• Set on assigne: this watch will be added to an issue when it is assigned to you, also if you do not already have a watch on it

For all thes there are system defaults set up by you JIRA administrator, but if you want other watches this is the place to define them. Simply click on the watch you want to change, select in the dropdown list that appers, click the OK button and you're done.

The autowatch table lists the projects and issue types where you want watches created automatically for you. If you leave issue type field empty watches will be created automatically for all issue types. You also have to select what type of watch you want and if you want to be notified immediately when the issue is created.

Automatically created watches looks and behaves like all other watches in the issue page, you can change the type of watch or remove them completely like any other watch. 

Other profile settings

Smartwatch also uses some standard JIRA profile settings from the Preferences section:

The 'Email Type' setting will determine whether you get notifications in HTML or text format. Smartwatch uses the standard JIRA templates, so the content of the notifications will be the same. Also the 'My Changes' setting will affect smartwatch, if it is set to 'Do not notify me' you will not get any notifications for your own changes. 

Introduction to Smartwatch

If you have worked with JIRA you probably have used the watch function. JIRA allows you to watch issues. If you do you will get emails when there are changes made to the issue.

The mails are good: you can see what has happend, and you get a link to open the issue. But you will probably get a lot of them, at least if you are in an organisation where many users work on the same issue. And will some of them will give you valuable information, others will be pretty uninteresting, or even spam.

Goal

So the main goal of Smartwatch for JIRA is to solve this. Smartwatch for JIRA allows you to get notified only for changes you care about. You will get rid of at least some of the spam in your mailbox. Another effect is that since you can set up watches that only trigger for example when an issue is Ready, you can use it also for users that don't actually work on an issue, but are interested in knowing when you have solved it.

Basic assumptions

The design of Smartwatch for JIRA is based on a few assumptions:

• most users are not interested in all changes, but rather in a subset. While changes in some fields might be very interesting, changes in others are not.
• different users are interested on different changes, so they should be able to set different watches on the same issue. This might be based on their roles, or might be just personal preferences.
• some issues are more interesting for a user than others. While you might be interested in being notified for almost everything on the issues you are working on, you will probably want only the most important updates for others

Issue view

The key functionality of Smartwatch is in the little table Smartwatch adds to the issue page:

As you can see there are three watches for the current issue. Erik, the logged in user (logged in user is always displayed first) watches changes in the content (description, comments etc), admin wants to know when status changes, and Axel just wants to know when the issue is ready. More on this in the users guide.

Watches can be created by hand, simply by entering them in the issue page, or automatically. Users can set up in their profile that they want watches automatically created for them. Any way you can remove or modify any watch in the issue page.

Smartwatch uses watch rules, to define what changes you should be notified about. You get a set of rules set up for you automatically when you install the plugin, but you can customize those, add your own rules or deactivate the predefined ones. Check out the setup guide.