public class

IssueResource

extends Object
java.lang.Object
   ↳ com.atlassian.jira.rest.v2.issue.IssueResource

Summary

Public Constructors
IssueResource(JiraAuthenticationContext authContext, UserManager userManager, VoteService voteService, I18nHelper i18n, WatchersFinder watchersFinder, WatcherService watcherService, BeanBuilderFactory beanBuilderFactory, ContextUriInfo contextUriInfo, IssueFinder issueFinder, CreateIssueResource createIssueResource, UpdateIssueResource updateIssueResource, DeleteIssueResource deleteIssueResource, RemoteIssueLinkResource remoteIssueLinkResource, IssueWorklogResource issueWorklogResource, CommentResource commentResource, IssueWorkflowManager issueWorkflowManager, AssignIssueResource assignIssueResource, AdhocNotificationService notificationService, JiraBaseUrls jiraBaseUrls, IssuePicker issuePicker, JiraAvatarSupport jiraAvatarSupport, OrderByRequestParser orderByRequestParser, ResponseFactory responseFactory, IssuePropertiesLoader issuePropertiesLoader)
Public Methods
Response addComment(String issueIdOrKey, String expand, CommentJsonBean request)
Adds a new comment to an issue.
Response addVote(String issueIdOrKey)
Cast your vote in favour of an issue.
Response addWatcher(String issueIdOrKey, String userName)
Adds a user to an issue's watcher list.
Response addWorklog(String issueIdOrKey, String adjustEstimate, String newEstimate, String reduceBy, WorklogJsonBean request)
Adds a new worklog entry to an issue.
Response assign(String issueIdOrKey, UserBean assigneeBean)
Assigns an issue to a user.
Response createIssue(IssueUpdateBean createRequest)
Creates an issue or a sub-task from a JSON representation.
Response createIssues(IssuesUpdateBean createRequest)
Creates issues or sub-tasks from a JSON representation.
Response createOrUpdateRemoteIssueLink(String issueIdOrKey, RemoteIssueLinkCreateOrUpdateRequest request)
Creates or updates a remote issue link from a JSON representation.
Response deleteComment(String issueIdOrKey, String commentId)
Deletes an existing comment .
Response deleteIssue(String issueIdOrKey, String deleteSubtasks)
Delete an issue.
Response deleteRemoteIssueLinkByGlobalId(String issueIdOrKey, String globalId)
Delete the remote issue link with the given global id on the issue.
Response deleteRemoteIssueLinkById(String issueIdOrKey, String remoteIssueLinkId)
Delete the remote issue link with the given id on the issue.
Response deleteWorklog(String issueIdOrKey, String worklogId, String adjustEstimate, String newEstimate, String increaseBy)
Deletes an existing worklog entry .
Response doTransition(String issueIdOrKey, IssueUpdateBean issueUpdateBean)
Perform a transition on an issue.
Response editIssue(String issueIdOrKey, IssueUpdateBean updateRequest)
Edits an issue from a JSON representation.
Response getComment(String issueIdOrKey, String commentId, String expand)
Returns a single comment.
Response getComments(String issueIdOrKey, Long startAt, Integer maxResults, String orderBy, String expand)
Returns all comments for an issue.
Response getCreateIssueMeta(List<StringList> projectIds, List<StringList> projectKeys, List<StringList> issuetypeIds, List<String> issuetypeNames)
Returns the meta data for creating issues.
Response getEditIssueMeta(String issueIdOrKey)
Returns the meta data for editing an issue.
Response getIssue(String issueIdOrKey, List<StringList> fields, String expand, List<StringList> properties)
Returns a full representation of the issue for the given issue key.
Response getIssuePickerResource(String query, String currentJQL, String currentIssueKey, String currentProjectId, boolean showSubTasks, boolean showSubTaskParent)
Returns suggested issues which match the auto-completion query for the user which executes this request.
Response getIssueWatchers(String issueIdOrKey)
Returns the list of watchers for the issue with the given key.
Response getIssueWorklog(String issueIdOrKey)
Returns all work logs for an issue.
Response getRemoteIssueLinkById(String issueIdOrKey, String linkId)
Get the remote issue link with the given id on the issue.
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)
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.
Response getVotes(String issueIdOrKey)
A REST sub-resource representing the voters on the issue.
Response getWorklog(String issueIdOrKey, String worklogId)
Returns a specific worklog.
Response notify(String issueIdOrKey, NotificationJsonBean request)
Sends a notification (email) to the list or recipients defined in the request.
Response removeVote(String issueIdOrKey)
Remove your vote from an issue.
Response removeWatcher(String issueIdOrKey, String userName)
Removes a user from an issue's watcher list.
Response updateComment(String issueIdOrKey, String commentId, String expand, CommentJsonBean request)
Updates an existing comment using its JSON representation.
Response updateRemoteIssueLink(String issueIdOrKey, String linkId, RemoteIssueLinkCreateOrUpdateRequest updateRequest)
Updates a remote issue link from a JSON representation.
Response updateWorklog(String issueIdOrKey, String worklogId, String adjustEstimate, String newEstimate, WorklogJsonBean request)
Updates an existing worklog entry using its JSON representation.
Protected Methods
Response BAD_REQUEST()
Returns a Response with a status code of 400.
static Response NO_CONTENT()
Returns a Response with a status code of 204.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public IssueResource (JiraAuthenticationContext authContext, UserManager userManager, VoteService voteService, I18nHelper i18n, WatchersFinder watchersFinder, WatcherService watcherService, BeanBuilderFactory beanBuilderFactory, ContextUriInfo contextUriInfo, IssueFinder issueFinder, CreateIssueResource createIssueResource, UpdateIssueResource updateIssueResource, DeleteIssueResource deleteIssueResource, RemoteIssueLinkResource remoteIssueLinkResource, IssueWorklogResource issueWorklogResource, CommentResource commentResource, IssueWorkflowManager issueWorkflowManager, AssignIssueResource assignIssueResource, AdhocNotificationService notificationService, JiraBaseUrls jiraBaseUrls, IssuePicker issuePicker, JiraAvatarSupport jiraAvatarSupport, OrderByRequestParser orderByRequestParser, ResponseFactory responseFactory, IssuePropertiesLoader issuePropertiesLoader)

Public Methods

public Response addComment (String issueIdOrKey, String expand, 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
expand optional flags: renderedBody (provides body rendered in HTML)
request json body of request converted to a CommentJsonBean
Returns
  • the added comment

public 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

public 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

public 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

public 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

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

  • the issueType field must correspond to a sub-task issue type (you can use /issue/createmeta to discover sub-task issue types), and
  • you must provide a parent field in the issue create request containing the id or key of the parent issue.

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

public Response createIssues (IssuesUpdateBean createRequest)

Creates issues or sub-tasks from a JSON representation.

Creates many issues in one bulk operation.

Creating a sub-task is similar to creating a regular issue. More details can be found in createIssue section: createIssue(IssueUpdateBean)}

Parameters
createRequest IssuesUpdateBean which wraps issues to create in collection of IssueUpdateBean}
Returns
  • an com.atlassian.jira.rest.api.issue.IssueCreateResponse which encapsulates information about created issues and/or errors

public 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

public 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

public 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

public 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

public 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

public 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

public Response doTransition (String issueIdOrKey, IssueUpdateBean issueUpdateBean)

Perform a transition on an issue. When performing the transition you can update 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.

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

Specifying a "field_id": field_value in the "fields" is a shorthand for a "set" operation in the "update" section.
Field should appear either in "fields" or "update", not in both.

Parameters
issueIdOrKey the issue id or key to update (i.e. JRA-1330)

public Response getComment (String issueIdOrKey, String commentId, String expand)

Returns a single comment.

Parameters
issueIdOrKey of the issue the comment belongs to
commentId the ID of the comment to request
expand optional flags: renderedBody (provides body rendered in HTML)
Returns
  • a Response containing a CommentJsonBean

public Response getComments (String issueIdOrKey, Long startAt, Integer maxResults, String orderBy, String expand)

Returns all comments for an issue.

Results can be ordered by the "created" field which means the date a comment was added.

Parameters
issueIdOrKey to get comments for
startAt the page offset, if not specified then defaults to 0
maxResults how many results on the page should be included. Defaults to 50.
orderBy ordering of the results.
expand optional flags: renderedBody (provides body rendered in HTML)
Returns
  • all comments for the issue

public 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

public 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 editmeta.

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.

public Response getIssue (String issueIdOrKey, List<StringList> fields, String expand, List<StringList> properties)

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

  • *all - include all fields
  • *navigable - include just navigable fields
  • summary,comment - include just the summary and comments
  • -comment - include everything except comments (the default is *all for get-issue)
  • *all,-comment - include everything except comments

The properties param is similar to fields and specifies a comma-separated list of issue properties to include. Unlike fields, properties are not included by default. To include them all send ?properties=*all. You can also include only specified properties or exclude some properties with a minus (-) sign.

  • *all - include all properties
  • *all, -prop1 - include all properties except prop1
  • prop1, prop1 - include prop1 and prop2 properties

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.

The expand param is used to include, hidden by default, parts of response. This can be used to include:

  • renderedFields - field values in HTML format
  • names - display name of each field
  • schema - schema for each field which describes a type of the field
  • transitions - all possible transitions for the given issue
  • operations - all possibles operations which may be applied on issue
  • editmeta - information about how each field may be edited. It contains field's schema as well.
  • changelog - history of all changes of the given issue
  • versionedRepresentations - REST representations of all fields. Some field may contain more recent versions. RESET representations are numbered. The greatest number always represents the most recent version. It is recommended that the most recent version is used. version for these fields which provide a more recent REST representation. After including versionedRepresentations "fields" field become hidden.

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.
properties the list of properties to return for the issue. By default no properties are returned.
Returns
  • a Response containing a IssueBean

public Response getIssuePickerResource (String query, String currentJQL, String currentIssueKey, String currentProjectId, boolean showSubTasks, boolean showSubTaskParent)

Returns suggested issues which match the auto-completion query for the user which executes this request. This REST method will check the user's history and the user's browsing context and select this issues, which match the query.

Parameters
query the query.
currentJQL the JQL in context of which the request is executed. Only issues which match this JQL query will be included in results.
currentIssueKey the key of the issue in context of which the request is executed. The issue which is in context will not be included in the auto-completion result, even if it matches the query.
currentProjectId the id of the project in context of which the request is executed. Suggested issues will be only from this project.
showSubTasks if set to false, subtasks will not be included in the list.
showSubTaskParent if set to false and request is executed in context of a subtask, the parent issue will not be included in the auto-completion result, even if it matches the query.

public 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

public Response getIssueWorklog (String issueIdOrKey)

Returns all work logs for an issue.

Parameters
issueIdOrKey the worklogs belongs to
Returns
  • All worklogs for the issue

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

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

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

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

public 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

public 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

public 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

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

public 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

public Response updateComment (String issueIdOrKey, String commentId, String expand, 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
expand optional flags: renderedBody (provides body rendered in HTML)
request json body of request converted to a CommentJsonBean
Returns
  • updated Comment

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

public 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

Protected Methods

protected Response BAD_REQUEST ()

Returns a Response with a status code of 400.

Returns
  • a Response with a status code of 400.

protected static Response NO_CONTENT ()

Returns a Response with a status code of 204.

Returns
  • a Response with a status code of 204