Unfortunately, JIRA's due date does not cause automatic notification unless you tune it to send email reminders. This is a power user type of operation and unreachable by most JIRA users. Issue Reminders plugin allows any user to create reminders for the issues easily.
Adding New Reminders
You can add a new reminder to currently displayed issue in 3 ways:
- By using 'r', keyboard shortcut
- By selecting "Add New Reminder"
- By pressing "Add New Reminder" link in the Reminders right issue panel
All of these options display "Add New Reminder" dialog shown below.
| Summary | Summary of the Reminder, this is shown on the email message body by default email template. |
|---|---|
| Relative To | A reminder may be send on a specific day or specified hours before a date field of the issue, like due date. |
| Date/Time | Only shown "Relative To" field is set to None. Reminder email is send on selected date and time. Due to mail queu in and performance optimization there may be a few minutes delay. |
| Hours Before | Only shown a specific date field is chosen from "Relative To" field. Reminder email is send relative to selected "Relative To" field. For example if "Due Date" is chosen and "Hours Before" field is set to 48, reminder email is send 2 days before due date. |
| Period | Period can be daily, weekly, monthly or a Cron expression. If you select Cron Expression you also need to provide a valid cron expression in the corresponding field. |
| Cron Expression | Only valid if period field is set to Cron Expression. See corresponding tutorial on cron expressions and samples. |
| User | Select the users who will be notified with the emai. You can select multiple users here. |
| You can write email of any 3rd party which don't have JIRA account | |
| Project Role | Role you want to notify for the project of the issue |
| Group | The User group you like to send reminder to. Note that there may be a lot of users in a group and it may overload your JIRA or mail server if you are not careful. |
| Description | Description of the reminder. This is used in mail body of default email template |
| Private | Private reminders are only visible to you. Use this if you are using sensitive information in reminder summary or description. |
You have to select at least one reminder target, enter a summary information and a reminder date. Reminder date should be at least 5 minutes ahead of your time. Summary could be maximum 50 characters long and description could be maximum 150 characters long. If you enter multiple targets all of them will receive notification. If a user matches more than one target, he will receive notification only once. You cannot use rich text in summary and description fields, they all need to be in free text format. For security reasons HTML content is also escaped and will be displayed as plain text.
Each time a reminder is send a comment may also be created depending on add-on settings. Even if you delete the reminder you can check issue comments to see when a reminder is send.
Global Reminders
Global reminders are sent before issue deadline. These reminders are send to all users watching the issue, reporter and assignee of the issue. Reminders are send before configured amount of time before actual due date of the issue. You can configure how many hours before issue deadline a reminder will be send.You could completely disable reminders if you want from the plugin configurations page. It is off by default.
Issue Reminder List
All active and past reminders of an issue are displayed on the “Reminders” right of an issue. Active reminders are shown with a yellow post-it, and completed reminders are shown with a light blue post-it with a check mark on it.
You can also add new reminders or delete, edit existing reminders depending on the permission you have. For every reminder following information is displayed:
- Reminder’s recipient: For reminders with multiple recipient “Multiple Recipient” is displayed and if you hover on it, all recipients will be displayed in a tooltip. If recipient is a single user, hovering over it will show further details about the user.
- Reminder’s trigger time: The date on which the notification email will be sent or for expired notifications the date on which the reminder email is send.
- Reminder’s summary: If you hover on summary information, description of the reminder is also displayed as a tooltip.
Reminders Menu
Reminder list shown on the right hand side of an issue also host shortcut actions for the plugin. Pressing the arrow button next to "Add New Reminder" button opens the menu shown in the below screenshot.
You can quickly create a reminder for Tomorrow, or Next Week. These actions opens the reminder dialog but auto fills reminder due date. "My Reminders" action opens "My Reminders Page" explained below. Issues with My Reminders opens Issue Navigator with a JQL query which shows all issues with reminders created by you. A very similarly named action "Issues with Reminders for Me" also opens issue navigator with JQL but this time it shows all issues with Reminders whose recipient is you.
Deleting Reminders
If you do not have administrator rights you can only delete your own reminders. Project administrators could delete reminders in their own projects and JIRA administrators could delete all reminders. If you do not want to receive notification from a reminder just tell the reminder owner to remove you from reminder targets. If you delete an active reminder notification will not be sent. Deleting a past reminder will not have any effect other than removing data from the database. Since an already delivered notification has nearly no overhead on the system you generally do not need to delete them.
Editing Reminders
If you are owner of the reminder you can edit it. Editing a reminder is completely the same with creating a new reminder. The same reminder dialog is opened with previously entered information and you can change all attributes of the reminder.
My Reminders Page
You can see list of all reminders created by you using My Reminder Page. You can edit or delete reminders like you did in issue page. In active reminders are filtered out by default, just check "Include Inactive Reminders" checkbox to display list of inactive reminders. To open my reminders page click on the down arrow next to "Add New Reminder" action and select "My Reminders" menu item from the list.
Viewing Issues with Reminders
You can use JQL to query which issues has a reminder, either active or completed. There are 4 JQL functions and all of them starts with “issuesWithReminder” prefix:
- isuesWithReminder(“filterOutCompleted”): This is the most basic of all JQL functions. It just returns all issues with reminders. It takes one optional parameter to filter out issues with only completed reminders (default false).
Following queries returns all issues which has at least reminder (active or completed).
issue in issuesWithReminder() issue in issuesWithReminder(“false”)
Following query returns all issues which has at least one active reminder.
issue in issuesWithReminder("true")
- issuesWithReminderOwnedBy(“username”, “filterOutCompleted”): This query returns issues which are owned (set up by) given username. It takes an additional optional parameter to filter out issues with only completed reminders (default false).
Following query returns all issues which has at least one reminder set up by user with username “ataoguz”
issue in issuesWithReminderOwnedBy("ataoguz", "false")
- issuesWithReminderForUser(“username”, “filterOutCompleted”): This query returns issues which has reminders set up for the given username. It takes an additional optional parameter to filter out issues with only completed reminders (default false).
Following query returns all issues which has at least one reminder set up for user with username “adaoguz”
issue in issuesWithReminderForUser("adaoguz", "false")
- issuesWithReminderForEmail(“email”, “filterOutCompleted”): This query returns issues which has reminders set up for the given email address. It takes an additional optional parameter to filter out issues with only completed reminders (default false).
Following query returns all issues which has at least one reminder set up for email address “externaluser@client.com”
issue in issuesWithReminderForUser("externaluser@client.com", "false")
- issuesWithReminderForRole(“rolename”, “filterOutCompleted”): This query returns issues which has reminders set up for the given project role. It takes an additional optional parameter to filter out issues with only completed reminders (default false). If you need to filter reminders for only a specific project add another JQL clause to filter projects as shown in the following example, without it query returns results from all projects.
Following query returns all issues which has at least one active reminder set up for project role “deployment-team” in ERP project.
issue in issuesWithReminderForRole("deployment-team", "true") AND project = "ERP"
- issuesWithReminderForGroup(“cm”, “filterOutCompleted”): This query returns issues which has reminders set up for user group. It takes an additional optional parameter to filter out issues with only completed reminders (default false).
Following query returns all issues which has at least one active reminder set up for cm(Configuration Management) group.
issue in issuesWithReminderForGroup("cm", "true")
Plugin Configuration
| Add Comment to Issue | If selected a comment is added to issue for every reminder send. |
|---|---|
| Use Default From Address | If selected from address of emails use the from address configured in email settings. If not selected from address uses the from email address of the reminder owner. |
| Allow users only to notify themselves | If selected user, email, role and group selection is removed from create reminder dialog and users are only allowed to send reminder to themselves. |
| Automatically Delete Old Reminders | If selected reminders are automatically deleted from the issue after they have send. |
| Global Due Date Reminder | If selected a reminder email is send before due date of every issue if a resolution is not set. |
| Hours before due date | Only active if Global Due Date Reminders are turned on and shows how many hours before an issue's due date a reminder is send. |
Plugin Template Configuration
You can change default email template used by the plugin from the settings. You can use variables from reminder itself or issue to add information to email body or subject. List of available variables are also available inside plugins template configuration page. Click on the question mark icon next to template to display it. Templates are Velocity templates, you can use any Velocity keyword inside the template. If you want to return to default template, just delete everything and save as empty, it will automatically revert to default template.
| Variable | Description |
|---|---|
| $baseURL | URL of JIRA |
| $issueLink | URL of issue |
| URL of issue | URL of issue icon |
| $issueHTMLDescription | Issue description as HTML |
| Issue description as HTML | Issue key |
| $issue.summary | Issue summary |
| $issue.assignee.displayName | Name of issue assignee |
| $issue.reporter.displayName | Name of issue reporter |
| $issue.project.name | Name of project |
| $issue.project.key | $issue.project.key |
| $issue.statusObject.name | Status of the issue |
| $issue.resolutionObject.name | $issue.resolutionObject.name |
| $reminderOwnerDisplayName | Name of the user who created the reminder |
| $reminderOwnerAvatar | Avatar URL of the user who created the reminder |
| $reminder.summary | $reminder.summary |
| $reminder.longDescription | Description of reminder |
| $remainingDuration | Remaining duration until End Date of reminder, or Due Date/Relative Date of issue |
| $remainingDurationInDays | Remaining duration in days until End Date of reminder, or Due Date/Relative Date of issue |
| Any Custom Field | $reminderService.getCustomFieldValue($issue, "Name of Custom Field") |
FQA
- What happens when I move an issue from one project to another? All reminders of the issue will remain as it is. Since reminder email will contain description and summary of the issue, you may want to remove some of the reminders if the issue is a concern. Also if owner of the reminder does not have access to new project he/she may not see and delete this reminder. Project admin of current project may delete those reminders.
- How can I update a reminder? You can update uncompleted reminders. Once a reminder is send you can't update it. You need to delete the existing reminder and create a new one. This will be added in a future version.
- Are past reminders automatically deleted? They are deleted only if you activate automatic deletion from the settings. Otherwise they remain but they only serve as an audit trial. Reminders are sent only once. If you activate automatic deletion they are deleted immediately after sending notification email. Of course you can manually delete them anytime you want.
- What happens when an issue with custom reminders also has a due date? Will it be two reminders or only one? It depends on the time between custom reminder trigger time and issue deadline (due date). If there are less than 5 minutes between issue deadline and custom reminder trigger time only customer reminder notification will be sent. If there are more than 5 minutes, user will receive two different notification emails; one for custom reminder and the other for due date.
- Which permissions are required to add a reminder? You should have view issue permission to add a reminder to an issue.
- If I delete an issue, are reminders still delivered? No of course not. They are also deleted with the issue.
- What happens to reminder of user after user is deleted? Active reminders are send with owner "X". If it is periodic reminder it is not re-scheduled.