Versions Compared

Old Version 22

changes.mady.by.user Deniz Oğuz

Saved on

compared with

New Version 23

changes.mady.by.user Deniz Oğuz

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Info
titleTip
Issue Reminders REST API is

...

available on Apiary. You can browse our API and generate source code for various programming languages.

...

All functions of the plugin are accessible with REST API, you can create/edit reminders for JIRA issues, delete reminders, query issues for reminders. 

Panel
borderColor#ffd351
titleBGColor#ffd351
titleWarning

(warning) 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. /jira may not be a part of the url for your instance.

Preparation

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. In order to use basic authentication you have to provide Authorization header in every request. Its value is created from your username and password. There are lots of online tools to create value of this header. 

Panel
borderColor#d04437
titleBGColor#d04437
titleSecurity Warning

(error) Don't Use Basic Authentication Without HTTPS, especially in untrusted environments. Username and password combination can be monitored if someone intercepts the connection between browser and JIRA server.

For a test environment with username admin and password admin value of Authorization header is "Basic YWRtaW46YWRtaW4=". 

All of REST APIs uses JSON, so you have to specify "Content-Type: application/json" in your requests. All methods will also return a JSON as a response. 

To test REST API it helps a lot to have a tool to monitor requests made to JIRA server or create custom requests. You can use developer tools of your browser, REST client plugin of IntelliJ IDEA or any platform specific tool. My favorites for MAC is PAW and for Fiddler for Windows. Both of them are wonderful applications. PAW has also source code generation functions, that is once you have statisfied with request parameters it can generate Java, Javascript, Python source code to perform that request.

...

You can either query reminders for an issue with issue id or with issue key, both of them returns the same response.

Code Block
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?issueId={id}

Both call will return a JSON document containing all the reminders related with an issue in the following format. 

Code Block
languagejs
[  
   {  

      "id":97,
      "issueId":10437,
      "issueKey":"ERP-38",
      "reminderDateStr":"01/17/2016 10:00 PM",
      "reminderEndDateStr":"",
      "longDescription":"This is description of reminder",
      "ownerUserKey":"admin",
      "active":false,
      "summary":"this is reminder summary",
      "dateReminderSend":1453364233180,
      "dateReminderSendStr":"01/21/2016 10:17 AM",
      "couldBeDeleted":true,
      "reminderTargets":[  
         {  
            "identifier":"admin",
            "displayName":"Admin User",
            "targetType":"USER",
            "ID":109
         },
         {  
            "identifier":"skyler",
            "displayName":"Skyler White",
            "targetType":"USER",
            "ID":110
         },
         {  
            "identifier":"10001",
            "displayName":"Developers",
            "targetType":"ROLE",
            "ID":111
         }
      ],
      "isPrivate":true,
      "keyOfRelativeToField":"duedate",
      "hoursBefore":2.0
   }
]

...

array of recipients of the reminder.

fieldDescription
identifierdepending of the targetType it could be either username, role id, email address or group id
displayNameuser readable format of identifier
targetType

type of recipient: USER, EMAIL, ROLE, GROUP

IDunique id of recipient field and generated by the plugin. Used to remove a recipient from a reminder

...

Panel
borderColor#ffd351
titleBGColor#ffd351
titleWarning

(warning) Plugin returns some other fields which are not shown above. These fields are still in the response for backward compatibility, you should not use them. Some of these fields are:

  • description (use longDescription instead)
  • userKey, userDisplayName, userName (use information inside reminderTargets array)
  • groupName (use information inside reminderTargets array)
  • projectId, projectRoleId ((use information inside reminderTargets array)

Deleting a Reminder 

You can delete a reminder using it's 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).

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

Getting Details of an Existing Reminder

You can get details of a reminder using following API endpoint. If reminder is private you need to be owner of the reminder or administrator of the project. If you don't have permission, it returns 403 (Forbidden). If given reminder is not found it returns 404 (Not Found).

Code Block
GET http://localhost:2990/jira/rest/com.deniz.jira.reminders/1.0/reminders/{id}

Response is a JSON string with all the details of the reminer.

Code Block
languagexml
{
    "id": 2,
    "issueId": 10002,
    "issueKey": "ERP-3",
    "email": "",
    "userKey": "",
    "userDisplayName": "",
    "groupName": "",
    "projectId": -1,
    "reminderDate": 1444209900000,
    "reminderEndDate": 1446069600000,
    "reminderDateStr": "10/07/2015 12:25 PM",
    "reminderEndDateStr": "10/29/2015",
    "description": "",
    "longDescription": "DESC",
    "ownerUserKey": "admin",
    "projectRoleId": -1,
    "active": false,
    "summary": "ttttttt",
    "dateReminderSend": 1444210126642,
    "dateReminderSendStr": "10/07/2015 12:28 PM",
    "couldBeDeleted": true,
    "period": "Weekly",
    "creationDate": 1444209900000,
    "creationDateStr": "10/07/2015 12:25 PM",
    "reminderTargets": [
        {
            "identifier": "admin",
            "displayName": "admin",
            "targetType": "USER",
            "ID": 4
        },
        {
            "identifier": "10000",
            "displayName": "Users",
            "targetType": "ROLE",
            "ID": 5
        },
        {
            "identifier": "jira-administrators",
            "targetType": "GROUP",
            "ID": 6
        }
    ],
    "isPrivate": true,
    "hoursBefore": 0.0
}

You can use following Java code to get list of all Reminders.

Code Block
languagejava
import java.io.IOException;
import org.apache.http.client.fluent.*;

public class SendRequest
{
  public static void main(String[] args) {
    sendRequest();
  }
  
  private static void sendRequest() {
    
    // Gettting List of All Reminders (GET )
    
    try {
      
      // Create request
      Content content = Request.Get("http://localhost:2990/jira/rest/com.deniz.jira.reminders/1.0/reminders/myReminders")
      
      // Add headers
      .addHeader("Authorization", "Basic YWRtaW46YWRtaW4=")
      .addHeader("Accept", "application/json")
      
      // Fetch request and return content
      .execute().returnContent();
      
      // Print content
      System.out.println(content);
    }
    catch (IOException e) { System.out.println(e); }
  }
}

Updating an Existing Reminder

Warning

In current version updating a reminder deletes and re-creates a reminder, for this reason id of the reminder change. Please use the new ID returned by this method to perform further operations on the reminder.

You can update a previous reminder. It has same security restrictions as explained in GET and DELETE methods. Updating a reminder is very similar to creating a new reminder. You are required to enter all the information required, not just a difference. Please use GET method to get reminder details, modify it and re-submit to update reminder.

Code Block
PUT http://localhost:2990/jira/rest/com.deniz.jira.reminders/1.0/reminders/{id}

For further details for method body and response please refer to "Adding New Reminder" section.

...

This time you have to provide reminder attributes in JSON format. Of course you are not required to send Id fields, they are created by reminder plugin itself. If request succeeds it returns a 201 (Created) response body contains created reminder in JSON format. 

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

Body of the request should be a JSON string.

Code Block
{  
   "issueKey":"ERP-3",
   "reminderDate":"1456689600000",
   "longDescription":"This is description of reminder",
   "summary":"this is reminder summary",
   "reminderTargets":[  
      {  
         "identifier":"admin",
         "targetType":"USER"
      },
      {  
         "identifier":"10001",
         "targetType":"ROLE"
      }
   ],
   "isPrivate":true,
   "keyOfRelativeToField":"duedate",
   "hoursBefore":2
}

Following is an example PHP code for adding above reminder to issue ERP-3

Code Block
languagephp
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'http://localhost:2990/jira/rest/com.deniz.jira.reminders/1.0/reminders');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Basic YWRtaW46YWRtaW4=",
  "Content-Type: application/json",
  "Accept: application/json",
 ]
);
// Create body
$json_array = [
            "summary" => "this is reminder summary",
            "reminderDate" => "1456689600000",
            "keyOfRelativeToField" => "duedate",
            "longDescription" => "This is description of reminder",
            "hoursBefore" => 2,
            "issueKey" => "ERP-3",
            "reminderTargets" => [
                [
                    "targetType" => "USER",
                    "identifier" => "admin"
                ],
                [
                    "targetType" => "ROLE",
                    "identifier" => "10001"
                ]
            ],
            "isPrivate" => true
        ]; 
$body = json_encode($json_array);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

Getting List of All Reminders by Logged in User

Info

In a future release this method will also accept a username.

Code Block
GET http://localhost:2990/jira/rest/com.deniz.jira.reminders/1.0/reminders/myReminders

...

 


Info
titleTip

Issue Reminders Java API is available here. You can use Java API for integration with your own apps or Script Runner scripts. Please check our Script Runner integration examples for more details.