#Reminders For JIRA

Not all issues but some issues require timely planning and most of the time, these type of issues are critical. Unfortunately, JIRAs 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.

##Adding New Reminders You can add a new reminder to currently displayed issue in 3 ways:

All of these options display “Add New Reminder” dialog shown below.

Add New Reminder

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.

You can create periodic reminders by selecting a period other than None. Weekly and Monthly, Yearly periods are possible. Each time a periodic reminder is send, a new reminder will be automatically created. If you want to cancel a periodic reminder just delete the active reminder.

Each time a reminder is send a comment is also created. 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 an issue deadline. Target of these reminders send to all users watching the issue, reporter and assignee of the issue. Reminders are sent before configured amount of time before actual due date of the issue. You can configure how many days before issue deadline a reminder will be sent, also you could completely disable reminders if you want, from the plugin configurations page.

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

Reminders for an Issue

You can also add new reminders from this panel, or delete existing reminders depending on the permission you have. For every reminder following information is displayed:

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

Deleting an Issue Reminder

##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:

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")

Following query returns all issues which has at least one reminder set up by user with username “ataoguz”

issue in issuesWithReminderOwnedBy("ataoguz", "false")

Following query returns all issues which has at least one reminder set up for user with username “adaoguz”

issue in issuesWithReminderForUser("adaoguz", "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")

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"

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 Currently plugin allows you to configure 3 properties:

Issue Reminders Plugin Settings

##REST API All functionality of the plugin can be accessed using Rest API.

Note that in the following examples url to access jira is “http://localhost:2990/jira”. You have to replace that url with your own JIRA URL.

Also all of the APIs require authentication. You have to provide an authentication accepted by your JIRA instance. In the following example “Basic Authentication” is used. You can use “Basic Authentication” as follows:

Authorization: Basic YWRtaW46YWRtaW4= (Actual Value depends on Encoded value of your password and username)

Since Rest API uses JSON format you also have to set Content-Type to JSON using following HTTP Header:

Content-Type: application/json

###Retrieving All Reminders for An Issue: You have two options to query for issue reminders. You can either query with issue id or with issue key. Both of them returns the same response.

GET http://localhost:2990/jira/rest/com.deniz.jira.reminders/1.0/reminders?issueKey={key}

GET http://localhost:2990/jira/rest/com.deniz.jira.reminders/1.0/reminders?issueKey=DEMO-5

or

GET http://localhost:2990/jira/rest/com.deniz.jira.reminders/1.0/reminders?issueId={id}

GET http://localhost:2990/jira/rest/com.deniz.jira.reminders/1.0/reminders?issueId=10004

Returned response is array of reminders in JSON Format:

[  
	{  
   		"id":4,
        "issueId":10004,
	    "email":"denizoguz@gmail.com",
    	"userKey":"admin",
        "userDisplayName":"admin",
	    "userName":"admin",
        "groupName":"jira-administrators",
	    "projectId":-1,
    	"reminderDate":1433839260000,
        "reminderDateStr":"09/Jun/15 11:41 AM",
	    "description":"This is reminder description",
    	"ownerUserKey":"admin",
        "projectRoleId":10002,
	    "projectRoleName":"Administrators",
    	"active":true,
        "summary":"Reminder Summary",
	    "couldBeDeleted":true
	}
]

Explanation of some fields are given below. Most fields are self explanatory.

id: This is the id of the reminder, you will need this if you want to delete a reminder.

issueId: Id of the issue for which the reminder is created.

projectId: It is not used, always -1. You can get this using JIRA’s own API and issueId field.

active: true if reminder is not delivered yet, false otherwise.

couldBeDeleted: true if requesting user has permission to delete this reminder, false otherwise.

Response also contains user displayable information for some fields. For example it returns date in two formats one is in EPOC format (1433839260000) the other one is in user displayable string format (09/Jun/15 11:41 AM). Others are projectRoleId/projectRoleName, userKey/userDisplayName.

###Deleting a Reminder

You can delete a reminder using its Id as a path parameter. You can only delete a reminder if you have permission to delete it. If operation succeeds it returns 200 (Ok) response without a body. If fails it returns 403 (Forbidden). If given reminder is not found it returns 404 (Not Found)

DELETE http://localhost:2990/jira/rest/com.deniz.jira.reminders/1.0/reminders/{id}

DELETE http://localhost:2990/jira/rest/com.deniz.jira.reminders/1.0/reminders/5

###Adding New Reminder

You can add new reminders using Rest API. This time you have to provide reminder attributes in JSON format.

POST http://localhost:2990/jira/rest/com.deniz.jira.reminders/1.0/reminders

Request body should contain reminder information in JSON format. Following is an example reminder. You have to specify at least one of “userKey”, “groupName”, “projectRoleId”.

{  
    "issueId":10004,
    "email":"denizoguz@gmail.com",
    "userKey":"admin",
    "userName":"admin",
    "groupName":"jira-administrators",
    "reminderDate":1433839260000,
    "description":"This is reminder description",
    "projectRoleId":10002,
    "summary":"Reminder Summary2"
}

If request succeeds it returns an 201 (Created) response body contains created reminder in JSON format, for example:

{  
	"id":6,
    "issueId":10004,
	"email":"denizoguz@gmail.com",
    "userKey":"admin",
	"userDisplayName":"",
    "groupName":"jira-administrators",
	"projectId":-1,
    "reminderDate":1433839260000,
	"description":"This is reminder description",
    "ownerUserKey":"",
	"projectRoleId":10002,
    "active":true,
	"summary":"Reminder Summary",
    "couldBeDeleted":false
}

period: Only include this field if you want to create a periodic reminder. Accepted values are Weekly, Monthly, Yearly

You can use returned id field to delete reminder any time you want.

All values are validated and should be correct, otherwise request is not accepted. If specified issue, or user, or project role is not found it returns 404 (Not Found) response. If you do not have access to project it returns 401 (Forbidden). Email syntax should be correct.

##FAQ

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

  2. How can I update a reminder? In the current version you can’t. You need to delete the existing reminder and create a new one. This will be added in a future version.

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

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

  5. Which permissions are required to add a reminder? You should have view issue permission to add a reminder to an issue.

  6. If I delete an issue, are reminders still delivered? No of course not. They are also deleted with the issue.