com.atlassian.jira.rest.v2.issue

Class UserResource

java.lang.Object

com.atlassian.jira.rest.v2.issue.UserResource

public class UserResource
extends Object

Since:

4.2

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_USERS_RETURNED
static int	MAX_USERS_RETURNED

Constructor Summary

Constructors

Constructor and Description

UserResource(UserService userService, UserUtil userUtil, PasswordPolicyManager passwordPolicyManager, I18nHelper i18n, EmailFormatter emailFormatter, JiraAuthenticationContext authContext, TimeZoneManager timeZoneManager, AvatarPickerHelper avatarPickerHelper, AvatarManager avatarManager, AvatarService avatarService, AttachmentHelper attachmentHelper, UserPropertyManager userPropertyManager, PermissionManager permissionManager, ProjectService projectService, IssueService issueService, ProjectManager projectManager, com.atlassian.event.api.EventPublisher eventPublisher, AssigneeService assigneeService, IssueManager issueManager, UserPickerResourceHelper userPickerHelper, JiraBaseUrls jiraBaseUrls, ColumnService columnService, XsrfInvocationChecker xsrfChecker, UserManager userManager, I18nHelper.BeanFactory beanFactory, ApplicationRoleManager applicationRoleManager, ApplicationRoleBeanConverter applicationRoleBeanConverter, UpdateUserApplicationHelper updateUserApplicationHelper, ResponseFactory responseFactory, ApplicationProperties applicationProperties)

Method Summary

Modifier and Type	Method and Description
javax.ws.rs.core.Response	addUserToApplication(String username, String applicationKey) Add user to given application.
javax.ws.rs.core.Response	changeUserPassword(String name, String key, PasswordBean passwordBean) Modify user password.
javax.ws.rs.core.Response	createAvatarFromTemporary(String username, AvatarCroppingBean croppingInstructions) Converts temporary avatar into a real avatar
javax.ws.rs.core.Response	createUser(UserWriteBean userBean) Create user.
javax.ws.rs.core.Response	defaultColumns(String username) Returns the default columns for the given user.
javax.ws.rs.core.Response	deleteAvatar(String username, Long id) Deletes avatar
javax.ws.rs.core.Response	findAssignableUsers(String name, String projectKey, String issueKey, Integer startAt, Integer maxResults, Integer actionDescriptorId, javax.ws.rs.core.UriInfo uriInfo) Returns a list of users that match the search string.
javax.ws.rs.core.Response	findBulkAssignableUsers(String name, String projectKeysStr, Integer startAt, Integer maxResults, javax.ws.rs.core.UriInfo uriInfo) Returns a list of users that match the search string and can be assigned issues for all the given projects.
javax.ws.rs.core.Response	findUsers(String username, Integer startAt, Integer maxResults, Boolean includeActive, Boolean includeInactive, javax.ws.rs.core.UriInfo uriInfo) Returns a list of users that match the search string.
javax.ws.rs.core.Response	findUsersForPicker(String query, Integer maxResults, Boolean showAvatar, List<String> excludeUsers) Returns a list of users matching query with highlighting.
javax.ws.rs.core.Response	findUsersWithAllPermissions(String name, String permissions, String issueKey, String projectKey, Integer startAt, Integer maxResults) Returns a list of active users that match the search string and have all specified permissions for the project or issue. This resource can be accessed by users with ADMINISTER_PROJECT permission for the project or global ADMIN or SYSADMIN rights.
javax.ws.rs.core.Response	findUsersWithBrowsePermission(String username, String issueKey, String projectKey, Integer startAt, Integer maxResults, javax.ws.rs.core.UriInfo uriInfo) Returns a list of active users that match the search string.
protected com.opensymphony.workflow.loader.ActionDescriptor	getActionDescriptorById(String issueKey, Integer actionDescriptorId)
Map<String,List<AvatarBean>>	getAllAvatars(String name) Returns all avatars which are visible for the currently logged in user.
javax.ws.rs.core.Response	getUser(String name, String key, boolean includeDeleted) Returns a user.
javax.ws.rs.core.Response	removeUser(String name, String key) Removes user and its references (like project roles associations, watches, history).
javax.ws.rs.core.Response	removeUserFromApplication(String username, String applicationKey) Remove user from given application.
javax.ws.rs.core.Response	resetColumns(String username) Reset the default columns for the given user to the system default.
javax.ws.rs.core.Response	setColumns(String username, List<String> fields) Sets the default columns for the given user.
javax.ws.rs.core.Response	storeTemporaryAvatar(String username, String filename, Long size, javax.servlet.http.HttpServletRequest request) Creates temporary avatar.
javax.ws.rs.core.Response	storeTemporaryAvatarUsingMultiPart(String username, com.atlassian.plugins.rest.common.multipart.FilePart filePart, javax.servlet.http.HttpServletRequest request) Creates temporary avatar using multipart.
javax.ws.rs.core.Response	updateUser(String name, String key, UserWriteBean userBean) Modify user.
javax.ws.rs.core.Response	updateUserAvatar(String username, AvatarBean avatarBean)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_USERS_RETURNED

public static final int DEFAULT_USERS_RETURNED

See Also:

Constant Field Values

MAX_USERS_RETURNED

public static final int MAX_USERS_RETURNED

See Also:

Constant Field Values

Constructor Detail

UserResource

public UserResource(UserService userService,
                    UserUtil userUtil,
                    PasswordPolicyManager passwordPolicyManager,
                    I18nHelper i18n,
                    EmailFormatter emailFormatter,
                    JiraAuthenticationContext authContext,
                    TimeZoneManager timeZoneManager,
                    AvatarPickerHelper avatarPickerHelper,
                    AvatarManager avatarManager,
                    AvatarService avatarService,
                    AttachmentHelper attachmentHelper,
                    UserPropertyManager userPropertyManager,
                    PermissionManager permissionManager,
                    ProjectService projectService,
                    IssueService issueService,
                    ProjectManager projectManager,
                    com.atlassian.event.api.EventPublisher eventPublisher,
                    AssigneeService assigneeService,
                    IssueManager issueManager,
                    UserPickerResourceHelper userPickerHelper,
                    JiraBaseUrls jiraBaseUrls,
                    ColumnService columnService,
                    XsrfInvocationChecker xsrfChecker,
                    UserManager userManager,
                    I18nHelper.BeanFactory beanFactory,
                    ApplicationRoleManager applicationRoleManager,
                    ApplicationRoleBeanConverter applicationRoleBeanConverter,
                    UpdateUserApplicationHelper updateUserApplicationHelper,
                    ResponseFactory responseFactory,
                    ApplicationProperties applicationProperties)

Method Detail

getUser

public javax.ws.rs.core.Response getUser(String name,
                                         String key,
                                         boolean includeDeleted)

Returns a user. This resource cannot be accessed anonymously.

Parameters:

name - the username

key - user key

includeDeleted - whether deleted users should be returned (flag available to users with global ADMIN rights)

findUsers

public javax.ws.rs.core.Response findUsers(String username,
                                           Integer startAt,
                                           Integer maxResults,
                                           Boolean includeActive,
                                           Boolean includeInactive,
                                           @Context
                                           javax.ws.rs.core.UriInfo uriInfo)

Returns a list of users that match the search string. This resource cannot be accessed anonymously.

Parameters:

username - A query string used to search username, name or e-mail address

startAt - the index of the first user to return (0-based)

maxResults - the maximum number of users to return (defaults to 50). The maximum allowed value is 1000. If you specify a value that is higher than this number, your search results will be truncated.

includeActive - If true, then active users are included in the results (default true)

includeInactive - If true, then inactive users are included in the results (default false)

uriInfo - context used for creating urls in user objects

Returns:

A list of user objects that match the username provided

findUsersForPicker

public javax.ws.rs.core.Response findUsersForPicker(String query,
                                                    Integer maxResults,
                                                    Boolean showAvatar,
                                                    List<String> excludeUsers)

Returns a list of users matching query with highlighting.

Parameters:

query - A string used to search username, Name or e-mail address

maxResults - the maximum number of users to return (defaults to 50). The maximum allowed value is 1000. If you specify a value that is higher than this number, your search results will be truncated.

Returns:

An object containing list of matched user objects, with html representing highlighting.

findAssignableUsers

public javax.ws.rs.core.Response findAssignableUsers(String name,
                                                     String projectKey,
                                                     String issueKey,
                                                     Integer startAt,
                                                     Integer maxResults,
                                                     Integer actionDescriptorId,
                                                     @Context
                                                     javax.ws.rs.core.UriInfo uriInfo)

Returns a list of users that match the search string. This resource cannot be accessed anonymously. Please note that this resource should be called with an issue key when a list of assignable users is retrieved for editing. For create only a project key should be supplied. The list of assignable users may be incorrect if it's called with the project key for editing.

Parameters:

name - the username

projectKey - the key of the project we are finding assignable users for

issueKey - the issue key for the issue being edited we need to find assignable users for.

startAt - the index of the first user to return (0-based)

maxResults - the maximum number of users to return (defaults to 50). The maximum allowed value is 1000. If you specify a value that is higher than this number, your search results will be truncated.

uriInfo - Context used for constructing user objects

Returns:

a Response with the users matching the query

createUser

@ExperimentalApi
public javax.ws.rs.core.Response createUser(UserWriteBean userBean)

Create user. By default created user will not be notified with email. If password field is not set then password will be randomly generated.

updateUser

@ExperimentalApi
public javax.ws.rs.core.Response updateUser(String name,
                                                             String key,
                                                             UserWriteBean userBean)

Modify user. The "value" fields present will override the existing value. Fields skipped in request will not be changed.

Parameters:

name - the username

key - user key

Returns:

a user

changeUserPassword

@ExperimentalApi
public javax.ws.rs.core.Response changeUserPassword(String name,
                                                                     String key,
                                                                     PasswordBean passwordBean)

Modify user password.

Parameters:

name - the username

key - user key

removeUser

@ExperimentalApi
public javax.ws.rs.core.Response removeUser(String name,
                                                             String key)

Removes user and its references (like project roles associations, watches, history).

Note: user references will not be removed if multiple User Directories are used and there is a user with the same name existing in another directory (shadowing user).

Parameters:

name - the username

key - user key

getActionDescriptorById

protected com.opensymphony.workflow.loader.ActionDescriptor getActionDescriptorById(String issueKey,
                                                                                    Integer actionDescriptorId)

findUsersWithBrowsePermission

public javax.ws.rs.core.Response findUsersWithBrowsePermission(String username,
                                                               String issueKey,
                                                               String projectKey,
                                                               Integer startAt,
                                                               Integer maxResults,
                                                               @Context
                                                               javax.ws.rs.core.UriInfo uriInfo)

Returns a list of active users that match the search string. This resource cannot be accessed anonymously and requires the Browse Users global permission. Given an issue key this resource will provide a list of users that match the search string and have the browse issue permission for the issue provided.

Parameters:

username - the username filter, no users returned if left blank

issueKey - the issue key for the issue being edited we need to find viewable users for.

projectKey - the optional project key to search for users with if no issueKey is supplied.

startAt - the index of the first user to return (0-based)

maxResults - the maximum number of users to return (defaults to 50). The maximum allowed value is 1000. If you specify a value that is higher than this number, your search results will be truncated.

uriInfo - Context used for constructing user objects

Returns:

a Response with the users matching the query

findUsersWithAllPermissions

public javax.ws.rs.core.Response findUsersWithAllPermissions(String name,
                                                             String permissions,
                                                             String issueKey,
                                                             String projectKey,
                                                             Integer startAt,
                                                             Integer maxResults)

Returns a list of active users that match the search string and have all specified permissions for the project or issue.
This resource can be accessed by users with ADMINISTER_PROJECT permission for the project or global ADMIN or SYSADMIN rights.

Parameters:

name - the username filter, list includes all users if unspecified

permissions - comma separated list of permissions for project or issue returned users must have, see Permissions JavaDoc for the list of all possible permissions.

issueKey - the issue key for the issue for which returned users have specified permissions.

projectKey - the optional project key to search for users with if no issueKey is supplied.

startAt - the index of the first user to return (0-based)

maxResults - the maximum number of users to return (defaults to 50). The maximum allowed value is 1000. If you specify a value that is higher than this number, your search results will be truncated.

Returns:

a Response with the users matching the query

findBulkAssignableUsers

public javax.ws.rs.core.Response findBulkAssignableUsers(String name,
                                                         String projectKeysStr,
                                                         Integer startAt,
                                                         Integer maxResults,
                                                         @Context
                                                         javax.ws.rs.core.UriInfo uriInfo)

Returns a list of users that match the search string and can be assigned issues for all the given projects.

Parameters:

name - the username

startAt - the index of the first user to return (0-based)

maxResults - the maximum number of users to return (defaults to 50). The maximum allowed value is 1000. If you specify a value that is higher than this number, your search results will be truncated.

projectKeysStr - the keys of the projects we are finding assignable users for, comma-separated

uriInfo - Context used for constructing user objects

getAllAvatars

public Map<String,List<AvatarBean>> getAllAvatars(String name)

Returns all avatars which are visible for the currently logged in user.

Parameters:

name - username

Returns:

all avatars for given user, which the logged in user has permission to see

Since:

v5.0

createAvatarFromTemporary

public javax.ws.rs.core.Response createAvatarFromTemporary(String username,
                                                           AvatarCroppingBean croppingInstructions)

Converts temporary avatar into a real avatar

Parameters:

username - username

croppingInstructions - cropping instructions

Returns:

created avatar

Since:

v5.0

updateUserAvatar

public javax.ws.rs.core.Response updateUserAvatar(String username,
                                                  AvatarBean avatarBean)

storeTemporaryAvatar

public javax.ws.rs.core.Response storeTemporaryAvatar(String username,
                                                      String filename,
                                                      Long size,
                                                      @Context
                                                      javax.servlet.http.HttpServletRequest request)

Creates temporary avatar. Creating a temporary avatar is part of a 3-step process in uploading a new avatar for a user: upload, crop, confirm.

The following examples shows these three steps using curl. The cookies (session) need to be preserved between requests, hence the use of -b and -c. The id created in step 2 needs to be passed to step 3 (you can simply pass the whole response of step 2 as the request of step 3).

 curl -c cookiejar.txt -X POST -u admin:admin -H "X-Atlassian-Token: no-check" \
   -H "Content-Type: image/png" --data-binary @mynewavatar.png \
   'http://localhost:8090/jira/rest/api/2/user/avatar/temporary?username=admin&filename=mynewavatar.png'

 curl -b cookiejar.txt -X POST -u admin:admin -H "X-Atlassian-Token: no-check" \
   -H "Content-Type: application/json" --data '{"cropperWidth": "65","cropperOffsetX": "10","cropperOffsetY": "16"}' \
   -o tmpid.json \
   http://localhost:8090/jira/rest/api/2/user/avatar?username=admin

 curl -b cookiejar.txt -X PUT -u admin:admin -H "X-Atlassian-Token: no-check" \
   -H "Content-Type: application/json" --data-binary @tmpid.json \
   http://localhost:8090/jira/rest/api/2/user/avatar?username=admin
 

Parameters:

username - username

filename - name of file being uploaded

size - size of file

request - servlet request

Returns:

temporary avatar cropping instructions

Since:

v5.0

storeTemporaryAvatarUsingMultiPart

public javax.ws.rs.core.Response storeTemporaryAvatarUsingMultiPart(String username,
                                                                    com.atlassian.plugins.rest.common.multipart.FilePart filePart,
                                                                    @Context
                                                                    javax.servlet.http.HttpServletRequest request)

Creates temporary avatar using multipart. The response is sent back as JSON stored in a textarea. This is because the client uses remote iframing to submit avatars using multipart. So we must send them a valid HTML page back from which the client parses the JSON from.

Creating a temporary avatar is part of a 3-step process in uploading a new avatar for a user: upload, crop, confirm. This endpoint allows you to use a multipart upload instead of sending the image directly as the request body.

You *must* use "avatar" as the name of the upload parameter:

 curl -c cookiejar.txt -X POST -u admin:admin -H "X-Atlassian-Token: no-check" \
   -F "avatar=@mynewavatar.png;type=image/png" \
   'http://localhost:8090/jira/rest/api/2/user/avatar/temporary?username=admin'
 

Parameters:

username - Username

request - servlet request

Returns:

temporary avatar cropping instructions

Since:

v5.0

deleteAvatar

public javax.ws.rs.core.Response deleteAvatar(String username,
                                              Long id)

Deletes avatar

Parameters:

username - username

id - database id for avatar

Returns:

temporary avatar cropping instructions

Since:

v5.0

defaultColumns

public javax.ws.rs.core.Response defaultColumns(String username)

Returns the default columns for the given user. Admin permission will be required to get columns for a user other than the currently logged in user.

Parameters:

username - username

Returns:

column configuration

Since:

v6.1

setColumns

public javax.ws.rs.core.Response setColumns(String username,
                                            List<String> fields)

Sets the default columns for the given user. Admin permission will be required to get columns for a user other than the currently logged in user.

Parameters:

username - username

fields - list of column ids

Returns:

javax.ws.rs.core.Response containing basic message and http return code

Since:

v6.1

resetColumns

public javax.ws.rs.core.Response resetColumns(String username)

Reset the default columns for the given user to the system default. Admin permission will be required to get columns for a user other than the currently logged in user.

Parameters:

username - username

Returns:

javax.ws.rs.core.Response containing basic message and http return code

Since:

v6.1

addUserToApplication

@ExperimentalApi
public javax.ws.rs.core.Response addUserToApplication(String username,
                                                                       String applicationKey)

Add user to given application. Admin permission will be required to perform this operation.

Parameters:

username - username

applicationKey - application key

Returns:

javax.ws.rs.core.Response containing basic message http return code

Since:

v7.0

removeUserFromApplication

@ExperimentalApi
public javax.ws.rs.core.Response removeUserFromApplication(String username,
                                                                            String applicationKey)

Remove user from given application. Admin permission will be required to perform this operation.

Parameters:

username - username

applicationKey - application key

Returns:

javax.ws.rs.core.Response containing basic message http return code

Since:

v7.0