com.atlassian.jira.rest.v2.issue
Class IssueResource

java.lang.Object
  extended by com.atlassian.jira.rest.v2.issue.IssueResource

public class IssueResource
extends Object

Since:
v4.2

Constructor Summary
IssueResource(JiraAuthenticationContext authContext, UserManager userManager, VoteService voteService, ContextI18n i18n, WatcherOps watcherOps, WatcherService watcherService, BeanBuilderFactory beanBuilderFactory, ContextUriInfo contextUriInfo, IssueFinder issueFinder, CreateIssueResource createIssueResource, UpdateIssueResource updateIssueResource, DeleteIssueResource deleteIssueResource, RemoteIssueLinkResource remoteIssueLinkResource, WorklogResource worklogResource, CommentResource commentResource, IssueWorkflowManager issueWorkflowManager, AssignIssueResource assignIssueResource, AdhocNotificationService notificationService)
           
 
Method Summary
 javax.ws.rs.core.Response addComment(String issueIdOrKey, CommentJsonBean request)
          Adds a new comment to an issue.
 javax.ws.rs.core.Response addVote(String issueIdOrKey)
          Cast your vote in favour of an issue.
 javax.ws.rs.core.Response addWatcher(String issueIdOrKey, String userName)
          Adds a user to an issue's watcher list.
 javax.ws.rs.core.Response addWorklog(String issueIdOrKey, String adjustEstimate, String newEstimate, String reduceBy, WorklogJsonBean request)
          Adds a new worklog entry to an issue.
 javax.ws.rs.core.Response assign(String issueIdOrKey, UserBean assigneeBean)
          Assigns an issue to a user.
protected  javax.ws.rs.core.Response BAD_REQUEST()
          Returns a Response with a status code of 400.
 javax.ws.rs.core.Response createIssue(IssueUpdateBean createRequest)
          Creates an issue or a sub-task from a JSON representation.
 javax.ws.rs.core.Response createOrUpdateRemoteIssueLink(String issueIdOrKey, RemoteIssueLinkCreateOrUpdateRequest request)
          Creates or updates a remote issue link from a JSON representation.
 javax.ws.rs.core.Response deleteComment(String issueIdOrKey, String commentId)
          Deletes an existing comment .
 javax.ws.rs.core.Response deleteIssue(String issueIdOrKey, String deleteSubtasks)
          Delete an issue.
 javax.ws.rs.core.Response deleteRemoteIssueLinkByGlobalId(String issueIdOrKey, String globalId)
          Delete the remote issue link with the given global id on the issue.
 javax.ws.rs.core.Response deleteRemoteIssueLinkById(String issueIdOrKey, String remoteIssueLinkId)
          Delete the remote issue link with the given id on the issue.
 javax.ws.rs.core.Response deleteWorklog(String issueIdOrKey, String worklogId, String adjustEstimate, String newEstimate, String increaseBy)
          Deletes an existing worklog entry .
 javax.ws.rs.core.Response doTransition(String issueIdOrKey, IssueUpdateBean issueUpdateBean)
          Perform a transition on an issue.
 javax.ws.rs.core.Response editIssue(String issueIdOrKey, IssueUpdateBean updateRequest)
          Edits an issue from a JSON representation.
 javax.ws.rs.core.Response getComments(String issueIdOrKey)
          Returns all comments for an issue.
 javax.ws.rs.core.Response getComments(String issueIdOrKey, String commentId)
          Returns a single comment.
 javax.ws.rs.core.Response getCreateIssueMeta(List<StringList> projectIds, List<StringList> projectKeys, List<StringList> issuetypeIds, List<String> issuetypeNames)
          Returns the meta data for creating issues.
 javax.ws.rs.core.Response getEditIssueMeta(String issueIdOrKey)
          Returns the meta data for editing an issue.
 javax.ws.rs.core.Response getIssue(String issueIdOrKey, List<StringList> fields, String expand)
          Returns a full representation of the issue for the given issue key.
 javax.ws.rs.core.Response getIssueWatchers(String issueIdOrKey)
          Returns the list of watchers for the issue with the given key.
 javax.ws.rs.core.Response getIssueWorklog(String issueIdOrKey)
          Returns all work logs for an issue.
 javax.ws.rs.core.Response getRemoteIssueLinkById(String issueIdOrKey, String linkId)
          Get the remote issue link with the given id on the issue.
 javax.ws.rs.core.Response getRemoteIssueLinks(String issueIdOrKey, String globalId)
          A REST sub-resource representing the remote issue links on the issue.
 Collection<FieldMetaBean> getRequiredFields(FieldScreenRenderer fieldScreenRenderer, Issue issue)
           
 javax.ws.rs.core.Response getTransitions(String issueIdOrKey, String transitionId)
          Get a list of the transitions possible for this issue by the current user, along with fields that are required and their types.
 javax.ws.rs.core.Response getVotes(String issueIdOrKey)
          A REST sub-resource representing the voters on the issue.
 javax.ws.rs.core.Response getWorklog(String issueIdOrKey, String worklogId)
          Returns a specific worklog.
protected static javax.ws.rs.core.Response NO_CONTENT()
          Returns a Response with a status code of 204.
 javax.ws.rs.core.Response notify(String issueIdOrKey, NotificationJsonBean request)
          Sends a notification (email) to the list or recipients defined in the request.
 javax.ws.rs.core.Response removeVote(String issueIdOrKey)
          Remove your vote from an issue.
 javax.ws.rs.core.Response removeWatcher(String issueIdOrKey, String userName)
          Removes a user from an issue's watcher list.
 javax.ws.rs.core.Response updateComment(String issueIdOrKey, String commentId, CommentJsonBean request)
          Updates an existing comment using its JSON representation.
 javax.ws.rs.core.Response updateRemoteIssueLink(String issueIdOrKey, String linkId, RemoteIssueLinkCreateOrUpdateRequest updateRequest)
          Updates a remote issue link from a JSON representation.
 javax.ws.rs.core.Response updateWorklog(String issueIdOrKey, String worklogId, String adjustEstimate, String newEstimate, WorklogJsonBean request)
          Updates an existing worklog entry using its JSON representation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

IssueResource

public IssueResource(JiraAuthenticationContext authContext,
                     UserManager userManager,
                     VoteService voteService,
                     ContextI18n i18n,
                     WatcherOps watcherOps,
                     WatcherService watcherService,
                     BeanBuilderFactory beanBuilderFactory,
                     ContextUriInfo contextUriInfo,
                     IssueFinder issueFinder,
                     CreateIssueResource createIssueResource,
                     UpdateIssueResource updateIssueResource,
                     DeleteIssueResource deleteIssueResource,
                     RemoteIssueLinkResource remoteIssueLinkResource,
                     WorklogResource worklogResource,
                     CommentResource commentResource,
                     IssueWorkflowManager issueWorkflowManager,
                     AssignIssueResource assignIssueResource,
                     AdhocNotificationService notificationService)
Method Detail

getTransitions

public javax.ws.rs.core.Response getTransitions(String issueIdOrKey,
                                                String transitionId)
Get a list of the transitions possible for this issue by the current user, along with fields that are required and their types.

Fields will only be returned if expand=transitions.fields.

The fields in the metadata correspond to the fields in the transition screen for that transition. Fields not in the screen will not be in the metadata.

Parameters:
issueIdOrKey - the issue whose transitions you want to view
Returns:
a response containing a Map of TransitionFieldBeans for each transition possible by the current user.

doTransition

public javax.ws.rs.core.Response doTransition(String issueIdOrKey,
                                              IssueUpdateBean issueUpdateBean)
Perform a transition on an issue. When performing the transition you can udate or set other issue fields.

The fields that can be set on transtion, in either the fields parameter or the update parameter can be determined using the /rest/api/2/issue/{issueIdOrKey}/transitions?expand=transitions.fields resource. If a field is not configured to appear on the transition screen, then it will not be in the transition metadata, and a field validation error will occur if it is submitted.

Parameters:
issueIdOrKey - the issue you want to transition
issueUpdateBean - The json containing the transition to peform and which field values to update.

removeVote

public javax.ws.rs.core.Response removeVote(String issueIdOrKey)
Remove your vote from an issue. (i.e. "unvote")

Parameters:
issueIdOrKey - the issue the current user is unvoting on
Returns:
a Response containing either NO_CONTENT or an error message.

addVote

public javax.ws.rs.core.Response addVote(String issueIdOrKey)
Cast your vote in favour of an issue.

Parameters:
issueIdOrKey - the issue to vote for
Returns:
a Response containing NO_CONTENT or an error message

getVotes

public javax.ws.rs.core.Response getVotes(String issueIdOrKey)
A REST sub-resource representing the voters on the issue.

Parameters:
issueIdOrKey - the issue to view voting information for
Returns:
a Response containing a VoteBean

getIssue

public javax.ws.rs.core.Response getIssue(String issueIdOrKey,
                                          List<StringList> fields,
                                          String expand)
Returns a full representation of the issue for the given issue key.

An issue JSON consists of the issue key, a collection of fields, a link to the workflow transition sub-resource, and (optionally) the HTML rendered values of any fields that support it (e.g. if wiki syntax is enabled for the description or comments).

The fields param (which can be specified multiple times) gives a comma-separated list of fields to include in the response. This can be used to retrieve a subset of fields. A particular field can be excluded by prefixing it with a minus.

By default, all (*all) fields are returned in this get-issue resource. Note: the default is different when doing a jql search -- the default there is just navigable fields (*navigable).

JIRA will attempt to identify the issue by the issueIdOrKey path parameter. This can be an issue id, or an issue key. If the issue cannot be found via an exact match, JIRA will also look for the issue in a case-insensitive way, or by looking to see if the issue was moved. In either of these cases, the request will proceed as normal (a 302 or other redirect will not be returned). The issue key contained in the response will indicate the current value of issue's key.

Parameters:
issueIdOrKey - the issue id or key to request (i.e. JRA-1330)
fields - the list of fields to return for the issue. By default, all fields are returned.
Returns:
a Response containing a IssueBean

getIssueWatchers

public javax.ws.rs.core.Response getIssueWatchers(String issueIdOrKey)
Returns the list of watchers for the issue with the given key.

Parameters:
issueIdOrKey - the issue key to request (i.e. JRA-1330)
Returns:
a Response containing a WatchersBean

addWatcher

public javax.ws.rs.core.Response addWatcher(String issueIdOrKey,
                                            String userName)
Adds a user to an issue's watcher list.

Parameters:
issueIdOrKey - a String containing an issue key
userName - the name of the user to add to the watcher list. If no name is specified, the current user is added.
Returns:
nothing

removeWatcher

public javax.ws.rs.core.Response removeWatcher(String issueIdOrKey,
                                               String userName)
Removes a user from an issue's watcher list.

Parameters:
issueIdOrKey - a String containing an issue key.
userName - a String containing the name of the user to remove from the watcher list. Must not be null.
Returns:
a 204 HTTP status if everything goes well

createIssue

public javax.ws.rs.core.Response createIssue(IssueUpdateBean createRequest)
Creates an issue or a sub-task from a JSON representation.

The fields that can be set on create, in either the fields parameter or the update parameter can be determined using the /rest/api/2/issue/createmeta resource. If a field is not configured to appear on the create screen, then it will not be in the createmeta, and a field validation error will occur if it is submitted.

Creating a sub-task is similar to creating a regular issue, with two important differences:

Parameters:
createRequest - an issue create request
Returns:
an com.atlassian.jira.rest.api.issue.IssueCreateResponse

deleteIssue

public javax.ws.rs.core.Response deleteIssue(String issueIdOrKey,
                                             String deleteSubtasks)
Delete an issue. If the issue has subtasks you must set the parameter deleteSubtasks=true to delete the issue. You cannot delete an issue without its subtasks also being deleted.

Parameters:
issueIdOrKey - a String containing an issue id or key
deleteSubtasks - a String of true or false indicating that any subtasks should also be deleted. If the issue has no subtasks this parameter is ignored. If the issue has subtasks and this parameter is missing or false, then the issue will not be deleted and an error will be returned.
Returns:
a 204 HTTP status if everything goes well

getCreateIssueMeta

public javax.ws.rs.core.Response getCreateIssueMeta(List<StringList> projectIds,
                                                    List<StringList> projectKeys,
                                                    List<StringList> issuetypeIds,
                                                    List<String> issuetypeNames)
Returns the meta data for creating issues. This includes the available projects, issue types and fields, including field types and whether or not those fields are required. Projects will not be returned if the user does not have permission to create issues in that project.

The fields in the createmeta correspond to the fields in the create screen for the project/issuetype. Fields not in the screen will not be in the createmeta.

Fields will only be returned if expand=projects.issuetypes.fields.

The results can be filtered by project and/or issue type, given by the query params.

Parameters:
projectIds - combined with the projectKeys param, lists the projects with which to filter the results. If absent, all projects are returned. This parameter can be specified multiple times, and/or be a comma-separated list. Specifiying a project that does not exist (or that you cannot create issues in) is not an error, but it will not be in the results.
projectKeys - combined with the projectIds param, lists the projects with which to filter the results. If null, all projects are returned. This parameter can be specified multiple times, and/or be a comma-separated list. Specifiying a project that does not exist (or that you cannot create issues in) is not an error, but it will not be in the results.
issuetypeIds - combinded with issuetypeNames, lists the issue types with which to filter the results. If null, all issue types are returned. This parameter can be specified multiple times, and/or be a comma-separated list. Specifiying an issue type that does not exist is not an error.
issuetypeNames - combinded with issuetypeIds, lists the issue types with which to filter the results. If null, all issue types are returned. This parameter can be specified multiple times, but is NOT interpreted as a comma-separated list. Specifiying an issue type that does not exist is not an error.
Returns:
a Response containing a CreateMetaBean

getEditIssueMeta

public javax.ws.rs.core.Response getEditIssueMeta(String issueIdOrKey)
Returns the meta data for editing an issue.

The fields in the editmeta correspond to the fields in the edit screen for the issue. Fields not in the screen will not be in the editemeta.

Parameters:
issueIdOrKey - the issue whose edit meta data you want to view
Returns:
a response containing a Map of FieldBeans for fields editable by the current user.

editIssue

public javax.ws.rs.core.Response editIssue(String issueIdOrKey,
                                           IssueUpdateBean updateRequest)
Edits an issue from a JSON representation. The issue can either be updated by setting explicit the field value(s) or by using an operation to change the field value.

The fields that can be updated, in either the fields parameter or the update parameter can be determined using the /rest/api/2/issue/{issueIdOrKey}/editmeta resource. If a field is not configured to appear on the edit screen, then it will not be in the editmeta, and a field validation error will occur if it is submitted.

Parameters:
issueIdOrKey - the issue id or key to update (i.e. JRA-1330)
Returns:
an com.atlassian.jira.rest.api.issue.IssueCreateResponse

assign

public javax.ws.rs.core.Response assign(String issueIdOrKey,
                                        UserBean assigneeBean)
Assigns an issue to a user. You can use this resource to assign issues when the user submitting the request has the assign permission but not the edit issue permission. If the name is "-1" automatic assignee is used. A null name will remove the assignee.

Parameters:
issueIdOrKey - a String containing an issue key
assigneeBean - A UserBean with the name of the user to assign the issue to.
Returns:
nothing

getRemoteIssueLinks

public javax.ws.rs.core.Response getRemoteIssueLinks(String issueIdOrKey,
                                                     String globalId)
A REST sub-resource representing the remote issue links on the issue.

Parameters:
issueIdOrKey - the issue to view the remote issue links for
globalId - The id of the remote issue link to be returned. If null (not provided) all remote links for the issue are returned.

For a fullexplanation of Issue Link fields please refer to https://developer.atlassian.com/display/JIRADEV/Fields+in+Remote+Issue+Links

Returns:
if no globalId is specified, a Response containing a List of RemoteIssueLinkBeans is returned. Otherwise, a Response containing a RemoteIssueLinkBean with the given globalId is returned.

getRemoteIssueLinkById

public javax.ws.rs.core.Response getRemoteIssueLinkById(String issueIdOrKey,
                                                        String linkId)
Get the remote issue link with the given id on the issue.

Parameters:
issueIdOrKey - the issue to view the remote issue links for
linkId - the id of the remote issue link
Returns:
a Response containing a RemoteIssueLinkBean.

createOrUpdateRemoteIssueLink

public javax.ws.rs.core.Response createOrUpdateRemoteIssueLink(String issueIdOrKey,
                                                               RemoteIssueLinkCreateOrUpdateRequest request)
Creates or updates a remote issue link from a JSON representation. If a globalId is provided and a remote issue link exists with that globalId, the remote issue link is updated. Otherwise, the remote issue link is created.

Parameters:
issueIdOrKey - the issue to create the remote issue link for
request - a request to create or update a remote issue link
Returns:
a RemoteIssueLinkCreateOrUpdateResponse

updateRemoteIssueLink

public javax.ws.rs.core.Response updateRemoteIssueLink(String issueIdOrKey,
                                                       String linkId,
                                                       RemoteIssueLinkCreateOrUpdateRequest updateRequest)
Updates a remote issue link from a JSON representation. Any fields not provided are set to null.

Parameters:
issueIdOrKey - the issue to update the remote issue link for
updateRequest - a request to update a remote issue link
Returns:
a Response containing either NO_CONTENT or an error message.

deleteRemoteIssueLinkById

public javax.ws.rs.core.Response deleteRemoteIssueLinkById(String issueIdOrKey,
                                                           String remoteIssueLinkId)
Delete the remote issue link with the given id on the issue.

Parameters:
issueIdOrKey - the issue to create the remote issue link for
remoteIssueLinkId - the id of the remote issue link
Returns:
a 204 HTTP status if everything goes well, otherwise the Response contains the error details

deleteRemoteIssueLinkByGlobalId

public javax.ws.rs.core.Response deleteRemoteIssueLinkByGlobalId(String issueIdOrKey,
                                                                 String globalId)
Delete the remote issue link with the given global id on the issue.

Parameters:
issueIdOrKey - the issue to create the remote issue link for
globalId - the global id of the remote issue link
Returns:
a 204 HTTP status if everything goes well, otherwise the Response contains the error details

getIssueWorklog

public javax.ws.rs.core.Response getIssueWorklog(String issueIdOrKey)
Returns all work logs for an issue.

Parameters:
issueIdOrKey - the worklogs belongs to
Returns:
All worklogs for the issue

getWorklog

public javax.ws.rs.core.Response getWorklog(String issueIdOrKey,
                                            String worklogId)
Returns a specific worklog.

Parameters:
issueIdOrKey - a string containing the issue id or key the worklog belongs to
worklogId - a String containing the work log id
Returns:
a worklog

updateWorklog

public javax.ws.rs.core.Response updateWorklog(String issueIdOrKey,
                                               String worklogId,
                                               String adjustEstimate,
                                               String newEstimate,
                                               WorklogJsonBean request)
Updates an existing worklog entry using its JSON representation.

Parameters:
issueIdOrKey - a string containing the issue id or key the worklog belongs to
worklogId - id of the worklog to be updated
adjustEstimate - (optional) allows you to provide specific instructions to update the remaining time estimate of the issue. Valid values are
  • "new" - sets the estimate to a specific value
  • "leave"- leaves the estimate as is
  • "auto"- Default option. Will automatically adjust the value based on the new timeSpent specified on the worklog
newEstimate - (required when "new" is selected for adjustEstimate) the new value for the remaining estimate field.
request - json body of request converted to a WorklogJsonBean
Returns:
updated worklog

deleteWorklog

public javax.ws.rs.core.Response deleteWorklog(String issueIdOrKey,
                                               String worklogId,
                                               String adjustEstimate,
                                               String newEstimate,
                                               String increaseBy)
Deletes an existing worklog entry .

Parameters:
issueIdOrKey - a string containing the issue id or key the worklog belongs to
worklogId - id of the worklog to be deleted
adjustEstimate - (optional) allows you to provide specific instructions to update the remaining time estimate of the issue. Valid values are
  • "new" - sets the estimate to a specific value
  • "leave"- leaves the estimate as is
  • "manual" - specify a specific amount to increase remaining estimate by
  • "auto"- Default option. Will automatically adjust the value based on the new timeSpent specified on the worklog
newEstimate - (required when "new" is selected for adjustEstimate) the new value for the remaining estimate field. e.g. "2d"
increaseBy - (required when "manual" is selected for adjustEstimate) the amount to increase the remaining estimate by e.g. "2d"
Returns:
No Content Response

addWorklog

public javax.ws.rs.core.Response addWorklog(String issueIdOrKey,
                                            String adjustEstimate,
                                            String newEstimate,
                                            String reduceBy,
                                            WorklogJsonBean request)
Adds a new worklog entry to an issue.

Parameters:
issueIdOrKey - a string containing the issue id or key the worklog will be added to
adjustEstimate - (optional) allows you to provide specific instructions to update the remaining time estimate of the issue. Valid values are
  • "new" - sets the estimate to a specific value
  • "leave"- leaves the estimate as is
  • "manual" - specify a specific amount to increase remaining estimate by
  • "auto"- Default option. Will automatically adjust the value based on the new timeSpent specified on the worklog
newEstimate - (required when "new" is selected for adjustEstimate) the new value for the remaining estimate field. e.g. "2d"
reduceBy - (required when "manual" is selected for adjustEstimate) the amount to reduce the remaining estimate by e.g. "2d"
request - json body of request converted to a WorklogJsonBean
Returns:
the added worklog

getComments

public javax.ws.rs.core.Response getComments(String issueIdOrKey)
Returns all comments for an issue.

Parameters:
issueIdOrKey - to get comments for
Returns:
all comments for the issue

getComments

public javax.ws.rs.core.Response getComments(String issueIdOrKey,
                                             String commentId)
Returns a single comment.

Parameters:
commentId - the ID of the comment to request
issueIdOrKey - of the issue the comment belongs to
Returns:
a Response containing a CommentJsonBean

updateComment

public javax.ws.rs.core.Response updateComment(String issueIdOrKey,
                                               String commentId,
                                               CommentJsonBean request)
Updates an existing comment using its JSON representation.

Parameters:
issueIdOrKey - a string containing the issue id or key the comment belongs to
commentId - id of the comment to be updated
request - json body of request converted to a CommentJsonBean
Returns:
updated Comment

deleteComment

public javax.ws.rs.core.Response deleteComment(String issueIdOrKey,
                                               String commentId)
Deletes an existing comment .

Parameters:
issueIdOrKey - a string containing the issue id or key the comment belongs to
commentId - id of the comment to be deleted
Returns:
No Content Response

addComment

public javax.ws.rs.core.Response addComment(String issueIdOrKey,
                                            CommentJsonBean request)
Adds a new comment to an issue.

Parameters:
issueIdOrKey - a string containing the issue id or key the comment will be added to
request - json body of request converted to a CommentJsonBean
Returns:
the added comment

notify

public javax.ws.rs.core.Response notify(String issueIdOrKey,
                                        NotificationJsonBean request)
Sends a notification (email) to the list or recipients defined in the request.

Parameters:
issueIdOrKey - a string containing the issue id or key the comment will be added to
request - json body of request converted to a NotificationJsonBean
Returns:

BAD_REQUEST

protected javax.ws.rs.core.Response BAD_REQUEST()
Returns a Response with a status code of 400.

Returns:
a Response with a status code of 400.

NO_CONTENT

protected static javax.ws.rs.core.Response NO_CONTENT()
Returns a Response with a status code of 204.

Returns:
a Response with a status code of 204

getRequiredFields

public Collection<FieldMetaBean> getRequiredFields(FieldScreenRenderer fieldScreenRenderer,
                                                   Issue issue)


Copyright © 2002-2013 Atlassian. All Rights Reserved.