@PublicApi public interface

UserService

com.atlassian.jira.bc.user.UserService
Known Indirect Subclasses

@PublicApi

This interface is designed for plugins to consume (call its methods).

Clients of @PublicApi can expect that programs compiled against a given version will remain binary compatible with later versions of the @PublicApi as per each product's API policy as long as the client does not implement/extend @PublicApi interfaces or classes (refer to each product's API policy for the exact guarantee---usually binary compatibility is guaranteed at least across minor versions).

Note: since @PublicApi interfaces and classes are not designed to be implemented or extended by clients, we may perform certain types of binary-incompatible changes to these classes and interfaces, but these will not affect well-behaved clients that do not extend/implement these types (in general, only classes and interfaces annotated with @PublicSpi are safe to extend/implement).

Class Overview

UserService provides User manipulation methods exposed for remote API and actions.

Summary

Nested Classes
class UserService.AddUserToApplicationValidationResult  
class UserService.CreateUserRequest This request contains all the instructions and user details that should be used during user validation and user creation. 
class UserService.CreateUserValidationResult  
class UserService.CreateUsernameValidationResult  
class UserService.DeleteUserValidationResult  
class UserService.FieldName  
class UserService.RemoveUserFromApplicationValidationResult  
class UserService.UpdateUserValidationResult  
Public Methods
void addUserToApplication(UserService.AddUserToApplicationValidationResult result)
Given a valid validation result, this will associate a user with an application by adding that user to all the default groups assigned to that application (regardless of the license).
ApplicationUser createUser(UserService.CreateUserValidationResult createUserValidationResult)
Create a new application user if the provided isValid().
ApplicationUser createUserFromSignup(UserService.CreateUserValidationResult result)
This method is deprecated. Use createUser(CreateUserValidationResult) instead. Since v7.0.
ApplicationUser createUserNoNotification(UserService.CreateUserValidationResult result)
This method is deprecated. Use createUser(CreateUserValidationResult) instead. Since v7.0.
ApplicationUser createUserWithNotification(UserService.CreateUserValidationResult result)
This method is deprecated. Use createUser(CreateUserValidationResult) instead. Since v7.0.
@Nonnull @ExperimentalApi ApplicationUserBuilder newUserBuilder(ApplicationUser user)
Allows you to construct ApplicationUser for validateUpdateUser(ApplicationUser)
void removeUser(ApplicationUser loggedInUser, UserService.DeleteUserValidationResult result)
This method is deprecated. Use removeUser(ApplicationUser, DeleteUserValidationResult) instead. Since v6.0.
void removeUserFromApplication(UserService.RemoveUserFromApplicationValidationResult result)
Given a valid validation result, this will disassociate a user from an application by removing that user from all the groups assigned to that application.
void updateUser(UserService.UpdateUserValidationResult updateUserValidationResult)
Execute the update using the validation result from validateUpdateUser(ApplicationUser).
UserService.AddUserToApplicationValidationResult validateAddUserToApplication(ApplicationUser loggedInUser, ApplicationUser user, ApplicationKey applicationKey)
Validates associating a user with an application.
UserService.AddUserToApplicationValidationResult validateAddUserToApplication(ApplicationUser user, ApplicationKey applicationKey)
This method is deprecated. Use validateAddUserToApplication(ApplicationUser, ApplicationUser, ApplicationKey) instead. Since v7.0
UserService.CreateUserValidationResult validateCreateUser(UserService.CreateUserRequest createUserRequest)
Validate that a new user can be created.
UserService.CreateUserValidationResult validateCreateUserForAdmin(ApplicationUser loggedInUser, String username, String password, String confirmPassword, String email, String fullname, Long directoryId)
This method is deprecated. Use validateCreateUser(CreateUserRequest) instead. Since v7.0.
UserService.CreateUserValidationResult validateCreateUserForAdmin(ApplicationUser loggedInUser, String username, String password, String confirmPassword, String email, String fullname)
This method is deprecated. Use validateCreateUser(CreateUserRequest) instead. Since v7.0.
UserService.CreateUserValidationResult validateCreateUserForSetup(ApplicationUser loggedInUser, String username, String password, String confirmPassword, String email, String fullname)
This method is deprecated. Use validateCreateUser(CreateUserRequest) instead. Since v7.0.
UserService.CreateUserValidationResult validateCreateUserForSignup(ApplicationUser loggedInUser, String username, String password, String confirmPassword, String email, String fullname)
This method is deprecated. Use validateCreateUser(CreateUserRequest) instead. Since v7.0.
UserService.CreateUserValidationResult validateCreateUserForSignupOrSetup(ApplicationUser user, String username, String password, String confirmPassword, String email, String fullname)
This method is deprecated. Use validateCreateUser(CreateUserRequest) instead. Since v7.0.
UserService.CreateUsernameValidationResult validateCreateUsername(ApplicationUser loggedInUser, String username, Long directoryId)
Validates the username for a new user.
UserService.CreateUsernameValidationResult validateCreateUsername(ApplicationUser loggedInUser, String username)
Validates the username for a new user.
UserService.DeleteUserValidationResult validateDeleteUser(ApplicationUser loggedInUser, String username)
Validates removing a user for the admin section.
UserService.DeleteUserValidationResult validateDeleteUser(ApplicationUser loggedInUser, ApplicationUser userForDelete)
Validates removing a user for the admin section.
@Deprecated @Internal UserService.RemoveUserFromApplicationValidationResult validateRemoveUserFromApplication(ApplicationUser user, ApplicationKey applicationKey)
This method is deprecated. Use validateRemoveUserFromApplication(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.user.ApplicationUser, com.atlassian.application.api.ApplicationKey) instead. Since v 7.0.0.
UserService.RemoveUserFromApplicationValidationResult validateRemoveUserFromApplication(ApplicationUser loggedInUser, ApplicationUser user, ApplicationKey applicationKey)
Validates disassociating a user from an application.
UserService.UpdateUserValidationResult validateUpdateUser(ApplicationUser user)
Validates updating a user's details.

Public Methods

public void addUserToApplication (UserService.AddUserToApplicationValidationResult result)

Given a valid validation result, this will associate a user with an application by adding that user to all the default groups assigned to that application (regardless of the license).

If the user is already associated with the application but is not the member of all the default groups, that user will be added to the default groups which that user does not belong to yet.

If any of the default groups assigned to this application are also assigned to other application(s), the user will also be associated with those applications as well.

This method is not the exact opposite to removeUserFromApplication(UserService.RemoveUserFromApplicationValidationResult). While this method only adds user to the default groups assigned to an application, removeUserFromApplication method removes user from all the group assigned to an application.

Parameters
result the validation result
Throws
AddException the underlying directory implementation failed to add user to group
PermissionException the underlying directory has been configured to not allow user to be added to group, or the directory/group is read-only

public ApplicationUser createUser (UserService.CreateUserValidationResult createUserValidationResult)

Create a new application user if the provided isValid(). This is typically called after performing validateCreateUser(CreateUserRequest) and verifying that the isValid(). If the request is not valid or validateCreateUser(CreateUserRequest) was not called prior to this method an IllegalStateException would get thrown.

Parameters
createUserValidationResult create user validation result returned from validateCreateUser(CreateUserRequest), this contains the user details and instructions used to create new user.
Returns
  • an application user representing the newly created user.
Throws
PermissionException when the logged in user does not have permissions to perform user creation or when the user directory is read-only.
CreateException if the user could not be created for any reason, eg username already exists
See Also

public ApplicationUser createUserFromSignup (UserService.CreateUserValidationResult result)

This method is deprecated.
Use createUser(CreateUserValidationResult) instead. Since v7.0.

Given a valid validation result, this will create the user using the details provided in the validation result. Email notification will be send to created user - via UserEventType.USER_SIGNUP event.

Parameters
result The validation result
Returns
  • The new user object that was created
Throws
CreateException if the user could not be created, eg username already exists
PermissionException If you cannot create users in this directory (it is read-only).

public ApplicationUser createUserNoNotification (UserService.CreateUserValidationResult result)

This method is deprecated.
Use createUser(CreateUserValidationResult) instead. Since v7.0.

Given a valid validation result, this will create the user using the details provided in the validation result. No email notification will be send to created user.

Parameters
result The validation result
Returns
  • The new user object that was created
Throws
CreateException if the user could not be created, eg username already exists
PermissionException If you cannot create users in this directory (it is read-only).

public ApplicationUser createUserWithNotification (UserService.CreateUserValidationResult result)

This method is deprecated.
Use createUser(CreateUserValidationResult) instead. Since v7.0.

Given a valid validation result, this will create the user using the details provided in the validation result. Email notification will be send to created user - via UserEventType.USER_CREATED event.

Parameters
result The validation result
Returns
  • The new user object that was created
Throws
CreateException if the user could not be created, eg username already exists
PermissionException If you cannot create users in this directory (it is read-only).

@Nonnull @ExperimentalApi public ApplicationUserBuilder newUserBuilder (ApplicationUser user)

@ExperimentalApi

This method is considered usable by external developers but its contracts have not stabilized.

Experimental APIs may be changed at any time before being marked @Internal or @PublicApi.

Allows you to construct ApplicationUser for validateUpdateUser(ApplicationUser)

public void removeUser (ApplicationUser loggedInUser, UserService.DeleteUserValidationResult result)

This method is deprecated.
Use removeUser(ApplicationUser, DeleteUserValidationResult) instead. Since v6.0.

Given a valid validation result, this will remove the user and removes the user from all the groups. All components lead by user will have lead cleared.

Parameters
loggedInUser the user performing operation
result The validation result

public void removeUserFromApplication (UserService.RemoveUserFromApplicationValidationResult result)

Given a valid validation result, this will disassociate a user from an application by removing that user from all the groups assigned to that application. This also validates if the directory where the user lives is not fully read-only.

If the group set assigned to this application is a superset of the group set assigned to other application(s), the user will also be disassociated with those applications as well.

This method is not the exact opposite to addUserToApplication(UserService.AddUserToApplicationValidationResult). While this method removes user from all the group assigned to an application, addUserToApplication method only adds user to the default groups assigned to an application

Parameters
result The validation result
Throws
RemoveException the underlying directory implementation failed to remove user from group
PermissionException the underlying directory has been configured to not allow user to be removed from group, or the directory/group is read-only

public void updateUser (UserService.UpdateUserValidationResult updateUserValidationResult)

Execute the update using the validation result from validateUpdateUser(ApplicationUser).

Parameters
updateUserValidationResult Result from the validation, which also contains all the user's details.
Throws
IllegalStateException if the validation result contains any errors.

public UserService.AddUserToApplicationValidationResult validateAddUserToApplication (ApplicationUser loggedInUser, ApplicationUser user, ApplicationKey applicationKey)

Validates associating a user with an application. This method checks if the logged in user has the permission to add user to application. It then checks if there is an application specified by the application key. It also checks if there are any default groups assigned to that application. It validates if there are any spaces in the application license as well. This also validates if the directory where the user lives is not fully read-only.

Parameters
loggedInUser The logged in user
user the user to be associated with the application
applicationKey the key of the application
Returns
  • a validation result containing appropriate errors or the details used to associate a user with an application

public UserService.AddUserToApplicationValidationResult validateAddUserToApplication (ApplicationUser user, ApplicationKey applicationKey)

This method is deprecated.
Use validateAddUserToApplication(ApplicationUser, ApplicationUser, ApplicationKey) instead. Since v7.0

Validates associating a user with an application. This method checks there is an application specified by the application key. It also checks if there are any default groups assigned to that application. It validates if there are any spaces in the application license as well. This also validates if the directory where the user lives is not fully read-only.

Parameters
user the user to be associated with the application
applicationKey the key of the application
Returns
  • a validation result containing appropriate errors or the details used to associate a user with an application

public UserService.CreateUserValidationResult validateCreateUser (UserService.CreateUserRequest createUserRequest)

Validate that a new user can be created. The validation instructions are specified in the UserService.CreateUserRequest.

Typical validations are:

  • Validate that specified (or default) application(s) has a seat available for the new user and that the default group(s) has been configured.
  • Validate that the specified logged in user is allowed to create a new user.
  • Validate that the specified or default user directory exists and is writable.
  • Validate that password conforms to password policy.
  • Validate that confirm password matches password (optional).
  • Validate that the new username is not currently in use.

createUser(CreateUserValidationResult) should only be called when the validationResult.isValid().

Usage example: 

 final CreateUserRequest createUserRequest = CreateUserRequest.withUserDetails(currentApplicationUser,
               username, password, email, displayName)
 result = userService.validateCreateUser(createUserRequest);
 if(result.isValid())
 {
    userService.createUser(createUserRequest);
 }
This request indicates that the user should be created in the default user directory with access to the default applications.

Parameters
createUserRequest user creation request containing new user details and validation instructions.
Returns
  • the result that would contain error messages when validation was not successful.

public UserService.CreateUserValidationResult validateCreateUserForAdmin (ApplicationUser loggedInUser, String username, String password, String confirmPassword, String email, String fullname, Long directoryId)

This method is deprecated.
Use validateCreateUser(CreateUserRequest) instead. Since v7.0.

Validates creating a user for the admin section. This method checks that external user management is disabled and that the user performing the operation has global admin rights. It also validates that all parameters (username, email, fullname) except for the password have been provided. Email is also checked to ensure that it is a valid email address. The username is required to be lowercase characters only and unique. The confirmPassword has to match the password provided.

This method allows the caller to name a directory to create the user in and the directoryId must be valid and represent a Directory with "create user" permission.

This validation differs from the 'ForSetup' and 'ForAdminPasswordRequired' validations as follows:

  • Does require global admin rights
  • The password is NOT required

Parameters
loggedInUser The remote user trying to add a new user
username The username of the new user. Needs to be lowercase and unique.
password The password for the new user.
confirmPassword The password confirmation. Needs to match password.
email The email for the new user. Needs to be a valid email address.
fullname The full name for the new user
directoryId The User Directory
Returns
  • a validation result containing appropriate errors or the new user's details

public UserService.CreateUserValidationResult validateCreateUserForAdmin (ApplicationUser loggedInUser, String username, String password, String confirmPassword, String email, String fullname)

This method is deprecated.
Use validateCreateUser(CreateUserRequest) instead. Since v7.0.

Validates creating a user for the admin section. This method checks that external user management is disabled and that the user performing the operation has global admin rights. It also validates that all parameters (username, email, fullname) except for the password have been provided. Email is also checked to ensure that it is a valid email address. The username is required to be lowercase characters only and unique. The confirmPassword has to match the password provided.

This validation differs from the 'ForSetup' and 'ForAdminPasswordRequired' validations as follows:

  • Does require global admin rights
  • The password is NOT required

Parameters
loggedInUser The remote user trying to add a new user
username The username of the new user. Needs to be lowercase and unique.
password The password for the new user.
confirmPassword The password confirmation. Needs to match password.
email The email for the new user. Needs to be a valid email address.
fullname The full name for the new user
Returns
  • a validation result containing appropriate errors or the new user's details

public UserService.CreateUserValidationResult validateCreateUserForSetup (ApplicationUser loggedInUser, String username, String password, String confirmPassword, String email, String fullname)

This method is deprecated.
Use validateCreateUser(CreateUserRequest) instead. Since v7.0.

Validates creating a user during setup of JIRA. This method does not check for a writable User Directory because the embedded crowd subsystem will not be initialised, and we know we will just have an Internal Directory during Setup. It also validates that all parameters (username, email, fullname, password) have been provided. Email is also checked to ensure that it is a valid email address. The username is required to be lowercase characters only and unique. The confirmPassword has to match the password provided.

This validation differs from the 'ForAdminPasswordRequired' and 'ForAdmin' validations as follows:

  • Does not require global admin rights
  • The password is required

Parameters
loggedInUser The remote user trying to add a new user
username The username of the new user. Needs to be lowercase and unique.
password The password for the new user.
confirmPassword The password confirmation. Needs to match password.
email The email for the new user. Needs to be a valid email address.
fullname The full name for the new user
Returns
  • a validation result containing appropriate errors or the new user's details

public UserService.CreateUserValidationResult validateCreateUserForSignup (ApplicationUser loggedInUser, String username, String password, String confirmPassword, String email, String fullname)

This method is deprecated.
Use validateCreateUser(CreateUserRequest) instead. Since v7.0.

Validates creating a user during public signup. This method checks that there is a writable User Directory available. It also validates that all parameters (username, email, fullname, password) have been provided. Email is also checked to ensure that it is a valid email address. The username is required to be lowercase characters only and unique. The confirmPassword has to match the password provided.

This validation differs from the 'ForAdminPasswordRequired' and 'ForAdmin' validations as follows:

  • Does not require global admin rights
  • The password is required

Parameters
loggedInUser The remote user trying to add a new user
username The username of the new user. Needs to be lowercase and unique.
password The password for the new user.
confirmPassword The password confirmation. Needs to match password.
email The email for the new user. Needs to be a valid email address.
fullname The full name for the new user
Returns
  • a validation result containing appropriate errors or the new user's details

public UserService.CreateUserValidationResult validateCreateUserForSignupOrSetup (ApplicationUser user, String username, String password, String confirmPassword, String email, String fullname)

This method is deprecated.
Use validateCreateUser(CreateUserRequest) instead. Since v7.0.

Validates creating a user during setup of JIRA or during public signup. This method checks that there is a writable User Directory available. It also validates that all parameters (username, email, fullname, password) have been provided. Email is also checked to ensure that it is a valid email address. The username is required to be lowercase characters only and unique. The confirmPassword has to match the password provided.

This validation differs from the 'ForAdminPasswordRequired' and 'ForAdmin' validations as follows:

  • Does not require global admin rights
  • The password is required

Parameters
user The remote user trying to add a new user
username The username of the new user. Needs to be lowercase and unique.
password The password for the new user.
confirmPassword The password confirmation. Needs to match password.
email The email for the new user. Needs to be a valid email address.
fullname The full name for the new user
Returns
  • a validation result containing appropriate errors or the new user's details

public UserService.CreateUsernameValidationResult validateCreateUsername (ApplicationUser loggedInUser, String username, Long directoryId)

Validates the username for a new user. The username is required to be lowercase characters only and unique in the given directory.

Parameters
loggedInUser The remote user trying to add a new user
username The username of the new user. Needs to be lowercase and unique.
directoryId The directory which the new user is intended to be created in.
Returns
  • a validation result containing appropriate errors

public UserService.CreateUsernameValidationResult validateCreateUsername (ApplicationUser loggedInUser, String username)

Validates the username for a new user. The username is required to be lowercase characters only and unique across all directories.

Parameters
loggedInUser The remote user trying to add a new user
username The username of the new user. Needs to be lowercase and unique.
Returns
  • a validation result containing appropriate errors

public UserService.DeleteUserValidationResult validateDeleteUser (ApplicationUser loggedInUser, String username)

Validates removing a user for the admin section. This method checks that external user management is disabled and that the user performing the operation has global admin rights. It also validates that username have been provided.

See validateDeleteUser(ApplicationUser, ApplicationUser) for restrictions.

Parameters
loggedInUser The remote user trying to remove a user
username The username of the user to remove. Needs to be valid
Returns
  • a validation result containing appropriate errors or the user object for delete

public UserService.DeleteUserValidationResult validateDeleteUser (ApplicationUser loggedInUser, ApplicationUser userForDelete)

Validates removing a user for the admin section. This method checks that external user management is disabled and that the user performing the operation has global admin rights. It also validates that username have been provided.

Removing the user is not allowed if:

  • Logged in user lacks global admin permissions
  • Logged in user and target user are the same user
  • Logged in user is not a system administrator but the target user is
  • Target user is the assignee for any issue
  • Target user is the reporter for any issue
  • Target user is the project lead for any project
  • A plugin that implements PreDeleteUserErrors rejects the request

Parameters
loggedInUser The remote user trying to remove a user
userForDelete The user to remove. Needs to be valid
Returns
  • a validation result containing appropriate errors or the user object for delete

@Deprecated @Internal public UserService.RemoveUserFromApplicationValidationResult validateRemoveUserFromApplication (ApplicationUser user, ApplicationKey applicationKey)

@Internal

This method is an internal implementation detail and will change without notice.

Clients that depend on @Internal classes and interfaces can not expect to be compatible with any version other than the version they were compiled against (even minor version and milestone releases may break binary compatibility with respect to @Internal elements).

This method is deprecated.
Use validateRemoveUserFromApplication(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.user.ApplicationUser, com.atlassian.application.api.ApplicationKey) instead. Since v 7.0.0.

Validates disassociating a user from an application. This method checks there is an application specified by the application key.

Method expects for loggedInUser to be available via getLoggedInUser().

Parameters
user the user to be disassociated with the application
applicationKey the key of the application
Returns
  • a validation result containing appropriate errors or the details used to disassociate a user from an application

public UserService.RemoveUserFromApplicationValidationResult validateRemoveUserFromApplication (ApplicationUser loggedInUser, ApplicationUser user, ApplicationKey applicationKey)

Validates disassociating a user from an application. This method checks there is an application specified by the application key.

Parameters
loggedInUser application user performing the application access removal
user the user to be disassociated with the application
applicationKey the key of the application
Returns
  • a validation result containing appropriate errors or the details used to disassociate a user from an application

public UserService.UpdateUserValidationResult validateUpdateUser (ApplicationUser user)

Validates updating a user's details.

Parameters
user The user details to update
Returns
  • A validation result containing any errors and all user details