UserService (OpenMRS 2.7.0-SNAPSHOT API)

All Superinterfaces:

OpenmrsService

All Known Implementing Classes:

UserServiceImpl
```
public interface UserService
extends OpenmrsService
```
Contains methods pertaining to Users in the system Use:
```
 
 
 List<User> users = Context.getUserService().getAllUsers();
 
```
See Also:

Context

Field Summary

Fields
Modifier and Type Field and Description

static String ADMIN_PASSWORD_LOCKED_PROPERTY

Fields
Modifier and Type	Field and Description
`static String`	`ADMIN_PASSWORD_LOCKED_PROPERTY`

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`changeHashedPassword(User user, String hashedPassword, String salt)` Changes the current user's password directly.
`void`	`changePassword(String oldPassword, String newPassword)` Changes the current user's password.
`void`	`changePassword(User user, String newPassword)` Changes password of `User` passed in
`void`	`changePassword(User user, String oldPassword, String newPassword)` Change user password.
`void`	`changePasswordUsingActivationKey(String activationKey, String newPassword)` Change user password given the activation key
`void`	`changePasswordUsingSecretAnswer(String secretAnswer, String pw)` Change user password given the answer to the secret question
`void`	`changeQuestionAnswer(String pw, String q, String a)` Changes the current user's secret question and answer.
`void`	`changeQuestionAnswer(User u, String question, String answer)` Changes the passed user's secret question and answer.
`User`	`createUser(User user, String password)` Create user with given password.
`String`	`generateSystemId()` Get/generate/find the next system id to be doled out.
`List<Privilege>`	`getAllPrivileges()` Returns all privileges currently possible for any User
`List<Role>`	`getAllRoles()` Returns all roles currently possible for any User
`List<User>`	`getAllUsers()` Returns all users in the system
`Integer`	`getCountOfUsers(String name, List<Role> roles, boolean includeRetired)` Return the number of users with a matching name or system id and have at least one of the given roles assigned to them
`Locale`	`getDefaultLocaleForUser(User user)`
`String`	`getLastLoginTime(User user)` Retrieves the last login time of the user in Unix Timestamp
`Privilege`	`getPrivilege(String p)` Returns Privilege in the system with given String privilege
`Privilege`	`getPrivilegeByUuid(String uuid)` Get Privilege by its UUID
`Role`	`getRole(String r)` Returns role object with given string role
`Role`	`getRoleByUuid(String uuid)` Get Role by its UUID
`String`	`getSecretQuestion(User user)` Returns secret question for the given user.
`User`	`getUser(Integer userId)` Get user by internal user identifier.
`User`	`getUserByActivationKey(String activationKey)` Gets a user with the specified activation key
`User`	`getUserByUsername(String username)` Get user by username (user's login identifier)
`User`	`getUserByUsernameOrEmail(String usernameOrEmail)` Gets a user by username or email
`User`	`getUserByUuid(String uuid)` Get user by the given uuid.
`List<User>`	`getUsers(String nameSearch, List<Role> roles, boolean includeVoided)` Return a list of users sorted by personName (see `PersonByNameComparator`) if any part of the search matches first/last/system id and the user has one at least one of the given `roles` assigned to them
`List<User>`	`getUsers(String name, List<Role> roles, boolean includeRetired, Integer start, Integer length)` Return a batch of users of a specific size sorted by personName (see `PersonByNameComparator`) if any part of the search matches first/last/system id and the user has one at least one of the given `roles` assigned to them.
`List<User>`	`getUsersByName(String givenName, String familyName, boolean includeRetired)` Search for a list of users by exact first name and last name.
`List<User>`	`getUsersByPerson(Person person, boolean includeRetired)` Get all user accounts that belong to a given person.
`List<User>`	`getUsersByRole(Role role)` Get users by role granted
`boolean`	`hasDuplicateUsername(User user)` true/false if username or systemId is already in db in username or system_id columns
`boolean`	`isSecretAnswer(User u, String answer)` Compares `answer` against the `user`'s secret answer.
`void`	`purgePrivilege(Privilege privilege)` Completely remove a privilege from the database
`void`	`purgeRole(Role role)` Complete remove a role from the database
`void`	`purgeUser(User user)` Completely remove a location from the database (not reversible).
`void`	`purgeUser(User user, boolean cascade)` Completely remove a user from the database (not reversible).
`User`	`removeUserProperty(User user, String key)` Removes the property denoted by `key` from the `user`'s properties.
`User`	`retireUser(User user, String reason)` Deactivate a user account so that it can no longer log in.
`Privilege`	`savePrivilege(Privilege privilege)` Save the given privilege in the database
`Role`	`saveRole(Role role)` Save the given role in the database
`User`	`saveUser(User user)` Updates a given `user` in the database.
`User`	`saveUserProperties(Map<String,String> properties)` Replaces all user properties with the given map of properties for the current user
`User`	`saveUserProperty(String key, String value)` Saves the current key/value as a user property for the current user.
`User`	`setUserActivationKey(User user)` Sets a user's activation key
`User`	`setUserProperty(User user, String key, String value)` Adds the `key`/`value` pair to the given `user`.
`User`	`unretireUser(User user)` Clears retired flag for a user.

Methods inherited from interface org.openmrs.api.OpenmrsService
onShutdown, onStartup

- Field Detail
  - ADMIN_PASSWORD_LOCKED_PROPERTY
```
static final String ADMIN_PASSWORD_LOCKED_PROPERTY
```
    See Also:
    
    Constant Field Values
- Method Detail
  - createUser
```
@Authorized(value="Add Users")
 @Logging(ignoredArgumentIndexes=1)
User createUser(User user,
                                                                                   String password)
                                                                            throws APIException
```
    Create user with given password.
    
    Parameters:
    
    user - the user to create
    
    password - the password for created user
    
    Returns:
    
    created user
    
    Throws:
    
    APIException
  - changePassword
```
@Authorized(value="Edit User Passwords")
 @Logging(ignoredArgumentIndexes={1,2})
void changePassword(User user,
                                                                                                     String oldPassword,
                                                                                                     String newPassword)
                                                                                              throws APIException
```
    Change user password.
    
    Parameters:
    
    user - the user to update password
    
    oldPassword - the user password to update
    
    newPassword - the new user password
    
    Throws:
    
    APIException - for not existing user and if old password is weak
    
    Since:
    
    1.12 Should throw APIException if old password is not correct Should throw APIException if new password is the same as old passoword Should throw APIException if given user does not exist Should change password for given user if oldPassword is correctly passed Should change password for given user if oldPassword is null and changing user have privileges Should throw exception if oldPassword is null and changing user have not privileges Should throw exception if new password is too short
  - getUser
```
@Authorized(value="Get Users")
User getUser(Integer userId)
                                     throws APIException
```
    Get user by internal user identifier.
    
    Parameters:
    
    userId - internal identifier
    
    Returns:
    
    requested user
    
    Throws:
    
    APIException - Should fetch user with given userId
  - getUserByUuid
```
@Authorized(value="Get Users")
User getUserByUuid(String uuid)
                                           throws APIException
```
    Get user by the given uuid.
    
    Parameters:
    
    uuid -
    
    Returns:
    
    user or null
    
    Throws:
    
    APIException - Should fetch user with given uuid Should find object given valid uuid Should return null if no object found with given uuid
  - getUserByUsername
```
@Authorized(value="Get Users")
User getUserByUsername(String username)
```
    Get user by username (user's login identifier)
    
    Parameters:
    
    username - User's identifier used for authentication
    
    Returns:
    
    requested user Should get user by username
  - getUserByUsernameOrEmail
```
@Authorized(value="Get Users")
User getUserByUsernameOrEmail(String usernameOrEmail)
```
    Gets a user by username or email
    
    Parameters:
    
    usernameOrEmail - User's email address or username
    
    Returns:
    
    requested user or null if not found
  - getUserByActivationKey
```
@Authorized(value="Get Users")
User getUserByActivationKey(String activationKey)
```
    Gets a user with the specified activation key
    
    Parameters:
    
    activationKey - User's activation key for password reset
    
    Returns:
    
    requested User with associated activation key
  - hasDuplicateUsername
```
@Authorized(value="Get Users")
boolean hasDuplicateUsername(User user)
                                                     throws APIException
```
    true/false if username or systemId is already in db in username or system_id columns
    
    Parameters:
    
    user - User to compare
    
    Returns:
    
    boolean
    
    Throws:
    
    APIException - Should verify that username and system id is unique
  - getUsersByRole
```
@Authorized(value="Get Users")
List<User> getUsersByRole(Role role)
                                                  throws APIException
```
    Get users by role granted
    
    Parameters:
    
    role - Role that the Users must have to be returned
    
    Returns:
    
    users with requested role
    
    Throws:
    
    APIException - Should fetch users assigned given role Should not fetch user that does not belong to given role
  - saveUser
```
@Authorized(value="Edit Users")
User saveUser(User user)
                                       throws APIException
```
    Updates a given user in the database.
    
    Parameters:
    
    user -
    
    Returns:
    
    the saved user
    
    Throws:
    
    APIException
  - retireUser
```
@Authorized(value="Edit Users")
User retireUser(User user,
                                                String reason)
                                         throws APIException
```
    Deactivate a user account so that it can no longer log in.
    
    Parameters:
    
    user -
    
    reason -
    
    Throws:
    
    APIException - Should retire user and set attributes
  - unretireUser
```
@Authorized(value="Edit Users")
User unretireUser(User user)
                                           throws APIException
```
    Clears retired flag for a user.
    
    Parameters:
    
    user -
    
    Throws:
    
    APIException - Should unretire and unmark all attributes
  - purgeUser
```
@Authorized(value="Purge Users")
void purgeUser(User user)
                                         throws APIException
```
    Completely remove a location from the database (not reversible). This method delegates to #purgeLocation(location, boolean) method.
    
    Parameters:
    
    user - the User to remove from the database. Should delete given user
    
    Throws:
    
    APIException
  - purgeUser
```
@Authorized(value="Purge Users")
void purgeUser(User user,
                                                boolean cascade)
                                         throws APIException
```
    Completely remove a user from the database (not reversible). This is a delete from the database. This is included for troubleshooting and low-level system administration. Ideally, this method should never be called — Users should be voided and not deleted altogether (since many foreign key constraints depend on users, deleting a user would require deleting all traces, and any historical trail would be lost). This method only clears user roles and attempts to delete the user record. If the user has been included in any other parts of the database (through a foreign key), the attempt to delete the user will violate foreign key constraints and fail.
    
    Parameters:
    
    cascade - true to delete associated content Should throw APIException if cascade is true Should delete given user when cascade equals false Should not delete user roles for given user when cascade equals false
    
    Throws:
    
    APIException
  - getAllPrivileges
```
@Authorized(value="Manage Privileges")
List<Privilege> getAllPrivileges()
                                                                 throws APIException
```
    Returns all privileges currently possible for any User
    
    Returns:
    
    Global list of privileges
    
    Throws:
    
    APIException - Should return all privileges in the system
  - getAllRoles
```
@Authorized(value="Manage Roles")
List<Role> getAllRoles()
                                                  throws APIException
```
    Returns all roles currently possible for any User
    
    Returns:
    
    Global list of roles
    
    Throws:
    
    APIException - Should return all roles in the system
  - saveRole
```
@Authorized(value="Manage Roles")
Role saveRole(Role role)
                                         throws APIException
```
    Save the given role in the database
    
    Parameters:
    
    role - Role to update
    
    Returns:
    
    the saved role
    
    Throws:
    
    APIException - Should throw error if role inherits from itself Should save given role to the database
  - purgeRole
```
@Authorized(value="Purge Roles")
void purgeRole(Role role)
                                         throws APIException
```
    Complete remove a role from the database
    
    Parameters:
    
    role - Role to delete from the database
    
    Throws:
    
    APIException - Should throw error when role is a core role Should return if role is null Should delete given role from database
  - savePrivilege
```
@Authorized(value="Manage Privileges")
Privilege savePrivilege(Privilege privilege)
                                                        throws APIException
```
    Save the given privilege in the database
    
    Parameters:
    
    privilege - Privilege to update
    
    Returns:
    
    the saved privilege
    
    Throws:
    
    APIException - Should save given privilege to the database
  - purgePrivilege
```
@Authorized(value="Purge Privileges")
void purgePrivilege(Privilege privilege)
                                                   throws APIException
```
    Completely remove a privilege from the database
    
    Parameters:
    
    privilege - Privilege to delete
    
    Throws:
    
    APIException - Should delete given privilege from the database Should throw error when privilege is core privilege
  - getRole
```
@Authorized(value="Get Roles")
Role getRole(String r)
                                     throws APIException
```
    Returns role object with given string role
    
    Returns:
    
    Role object for specified string
    
    Throws:
    
    APIException - Should fetch role for given role name
  - getRoleByUuid
```
@Authorized(value="Get Roles")
Role getRoleByUuid(String uuid)
                                           throws APIException
```
    Get Role by its UUID
    
    Parameters:
    
    uuid -
    
    Returns:
    
    role or null Should find object given valid uuid Should return null if no object found with given uuid
    
    Throws:
    
    APIException
  - getPrivilege
```
@Authorized(value="Get Privileges")
Privilege getPrivilege(String p)
                                                    throws APIException
```
    Returns Privilege in the system with given String privilege
    
    Returns:
    
    Privilege
    
    Throws:
    
    APIException - Should fetch privilege for given name
  - getPrivilegeByUuid
```
@Authorized(value="Get Privileges")
Privilege getPrivilegeByUuid(String uuid)
                                                          throws APIException
```
    Get Privilege by its UUID
    
    Parameters:
    
    uuid -
    
    Returns:
    
    privilege or null Should find object given valid uuid Should return null if no object found with given uuid Should fetch privilege for given uuid
    
    Throws:
    
    APIException
  - getAllUsers
```
@Authorized(value="Get Users")
List<User> getAllUsers()
                                               throws APIException
```
    Returns all users in the system
    
    Returns:
    
    Global list of users
    
    Throws:
    
    APIException - Should fetch all users in the system Should not contains any duplicate users
  - changePassword
```
@Authorized
 @Logging(ignoredArgumentIndexes={0,1})
void changePassword(String oldPassword,
                                                                        String newPassword)
                                                                 throws APIException
```
    Changes the current user's password.
    
    Parameters:
    
    oldPassword - current password
    
    newPassword - new password
    
    Throws:
    
    APIException - Should match on correctly hashed sha1 stored password Should match on incorrectly hashed sha1 stored password Should match on sha512 hashed password Should be able to update password multiple times Should respect locking via runtime properties
  - changePassword
```
@Authorized(value="Edit User Passwords")
void changePassword(User user,
                                                             String newPassword)
                                                      throws APIException
```
    Changes password of User passed in
    
    Parameters:
    
    user - user whose password is to be changed
    
    newPassword - new password to set
    
    Throws:
    
    APIException - Should update password of given user when logged in user has edit users password privilege Should not update password of given user when logged in user does not have edit users password privilege
  - changeHashedPassword
```
@Authorized(value="Edit User Passwords")
void changeHashedPassword(User user,
                                                                   String hashedPassword,
                                                                   String salt)
                                                            throws APIException
```
    Changes the current user's password directly. This is most useful if migrating users from other systems and you want to retain the existing passwords. This method will simply save the passed hashed password and salt directly to the database.
    
    Parameters:
    
    user - the user whose password you want to change
    
    hashedPassword - - the already hashed password to store
    
    salt - - the salt which should be used with this hashed password
    
    Throws:
    
    APIException
    
    Since:
    
    1.5 Should change the hashed password for the given user
  - changeQuestionAnswer
```
@Authorized(value="Edit User Passwords")
 @Logging(ignoredArgumentIndexes={1,2})
void changeQuestionAnswer(User u,
                                                                                                           String question,
                                                                                                           String answer)
                                                                                                    throws APIException
```
    Changes the passed user's secret question and answer.
    
    Parameters:
    
    u - User to change
    
    question -
    
    answer -
    
    Throws:
    
    APIException
    
    Since:
    
    1.5 Should change the secret question and answer for given user
  - changeQuestionAnswer
```
@Authorized
 @Logging(ignoreAllArgumentValues=true)
void changeQuestionAnswer(String pw,
                                                                              String q,
                                                                              String a)
                                                                       throws APIException
```
    Changes the current user's secret question and answer.
    
    Parameters:
    
    pw - user's password
    
    q - question
    
    a - answer
    
    Throws:
    
    APIException - Should match on correctly hashed stored password Should match on incorrectly hashed stored password
  - getSecretQuestion
```
String getSecretQuestion(User user)
                  throws APIException
```
    Returns secret question for the given user.
    
    Parameters:
    
    user -
    
    Returns:
    
    Throws:
    
    APIException
    
    Since:
    
    2.0
  - isSecretAnswer
```
@Logging(ignoredArgumentIndexes=1)
boolean isSecretAnswer(User u,
                                                          String answer)
                                                   throws APIException
```
    Compares answer against the user's secret answer.
    
    Parameters:
    
    u - user
    
    answer -
    
    Throws:
    
    APIException - Should return true when given answer matches stored secret answer Should return false when given answer does not match the stored secret answer
  - getUsers
```
@Authorized(value="Get Users")
List<User> getUsers(String nameSearch,
                                                   List<Role> roles,
                                                   boolean includeVoided)
                                            throws APIException
```
    Return a list of users sorted by personName (see PersonByNameComparator) if any part of the search matches first/last/system id and the user has one at least one of the given roles assigned to them
    
    Parameters:
    
    nameSearch - string to compare to the beginning of user's given/middle/family/family2 names
    
    roles - all the Roles the user must contain
    
    includeVoided - true/false whether to include voided users
    
    Returns:
    
    list of users matching the given attributes Should match search to familyName2 Should fetch voided users if includedVoided is true Should not fetch voided users if includedVoided is false Should fetch users with name that contains given nameSearch Should fetch users with systemId that contains given nameSearch Should fetch users with at least one of the given role objects Should not fetch duplicate users Should fetch all users if nameSearch is empty or null Should not fail if roles are searched but name is empty
    
    Throws:
    
    APIException
  - getUsersByName
```
@Authorized(value="Get Users")
List<User> getUsersByName(String givenName,
                                                         String familyName,
                                                         boolean includeRetired)
                                                  throws APIException
```
    Search for a list of users by exact first name and last name.
    
    Parameters:
    
    givenName -
    
    familyName -
    
    includeRetired -
    
    Returns:
    
    List<User> object of users matching criteria Should fetch users exactly matching the given givenName and familyName Should fetch voided users whenincludeVoided is true Should not fetch any voided users when includeVoided is false Should not fetch any duplicate users
    
    Throws:
    
    APIException
  - getUsersByPerson
```
@Authorized(value="Get Users")
List<User> getUsersByPerson(Person person,
                                                           boolean includeRetired)
                                                    throws APIException
```
    Get all user accounts that belong to a given person.
    
    Parameters:
    
    person -
    
    includeRetired -
    
    Returns:
    
    all user accounts that belong to person, including retired ones if specified
    
    Throws:
    
    APIException - Should fetch all accounts for a person when include retired is true Should not fetch retired accounts when include retired is false
  - setUserProperty
```
@Authorized
User setUserProperty(User user,
                                 String key,
                                 String value)
                          throws APIException
```
    Adds the key/value pair to the given user.
    Implementations of this method should handle privileges
    
    Parameters:
    
    user -
    
    key -
    
    value -
    
    Returns:
    
    the user that was passed in and added to Should return null if user is null Should throw error when user is not authorized to edit users Should add property with given key and value when key does not already exist Should modify property with given key and value when key already exists
    
    Throws:
    
    APIException
  - removeUserProperty
```
@Authorized
User removeUserProperty(User user,
                                    String key)
                             throws APIException
```
    Removes the property denoted by key from the user's properties. Implementations of this method should handle privileges
    
    Parameters:
    
    user -
    
    key -
    
    Returns:
    
    the user that was passed in and removed from Should return null if user is null Should throw error when user is not authorized to edit users Should remove user property for given user and key
    
    Throws:
    
    APIException
  - generateSystemId
```
@Authorized
String generateSystemId()
```
    Get/generate/find the next system id to be doled out. Assume check digit /not/ applied in this method
    
    Returns:
    
    new system id
  - getUsers
```
@Authorized(value="Get Users")
List<User> getUsers(String name,
                                                   List<Role> roles,
                                                   boolean includeRetired,
                                                   Integer start,
                                                   Integer length)
                                            throws APIException
```
    Return a batch of users of a specific size sorted by personName (see PersonByNameComparator) if any part of the search matches first/last/system id and the user has one at least one of the given roles assigned to them. If start and length are not specified, then all matches are returned, If name is empty or null, then all all users will be returned taking into consideration the values of start and length arguments.
    
    Parameters:
    
    name - string to compare to the beginning of user's given/middle/family/family2 names
    
    roles - all the Roles the user must contain
    
    includeRetired - true/false whether to include voided users
    
    start - beginning index for the batch
    
    length - number of users to return in the batch
    
    Returns:
    
    list of matching users of a size based on the specified arguments
    
    Throws:
    
    APIException
    
    Since:
    
    1.8 Should return users whose roles inherit requested roles
  - getCountOfUsers
```
@Authorized(value="Get Users")
Integer getCountOfUsers(String name,
                                                       List<Role> roles,
                                                       boolean includeRetired)
```
    Return the number of users with a matching name or system id and have at least one of the given roles assigned to them
    
    Parameters:
    
    name - patient name
    
    roles - all the Roles the user must contain
    
    includeRetired - Specifies whether voided users should be included
    
    Returns:
    
    the number of users matching the given attributes
    
    Since:
    
    1.8
  - saveUserProperty
```
@Authorized
User saveUserProperty(String key,
                                  String value)
```
    Saves the current key/value as a user property for the current user.
    
    Parameters:
    
    key - the authenticated user's property
    
    value - value of the property
    
    Since:
    
    1.10
  - saveUserProperties
```
@Authorized
User saveUserProperties(Map<String,String> properties)
```
    Replaces all user properties with the given map of properties for the current user
    
    Parameters:
    
    properties - the authenticated user's properties
    
    Since:
    
    1.10
  - changePasswordUsingSecretAnswer
```
@Authorized
void changePasswordUsingSecretAnswer(String secretAnswer,
                                                 String pw)
                                          throws APIException
```
    Change user password given the answer to the secret question
    
    Parameters:
    
    secretAnswer - the answer to secret question
    
    pw - the new password Should update password if secret is correct Should not update password if secret is not correct
    
    Throws:
    
    APIException
  - setUserActivationKey
```
@Authorized(value="Edit User Passwords")
User setUserActivationKey(User user)
                                                            throws MessageException
```
    Sets a user's activation key
    
    Parameters:
    
    user - The user for which the activation key will be set
    
    Throws:
    
    MessageException
  - changePasswordUsingActivationKey
```
void changePasswordUsingActivationKey(String activationKey,
                                      String newPassword)
```
    Change user password given the activation key
    
    Parameters:
    
    activationKey - the activation for password reset
    
    newPassword - the new password
  - getDefaultLocaleForUser
```
@Authorized
Locale getDefaultLocaleForUser(User user)
```
    Parameters:
    
    user - the User whose Locale to retrieve
    
    Returns:
    
    the default Locale of the given user, or the system locale if unspecified
    
    Since:
    
    2.3.6, 2.4.6, 2.5.4, 2.6.0
  - getLastLoginTime
```
@Authorized
String getLastLoginTime(User user)
```
    Retrieves the last login time of the user in Unix Timestamp
    
    Parameters:
    
    user - the subject user
    
    Returns:
    
    timestamp representing last login time (e.g. 1717414410587)
    
    Since:
    
    2.7.0

Interface UserService

Field Summary

Method Summary

Methods inherited from interface org.openmrs.api.OpenmrsService

Field Detail

ADMIN_PASSWORD_LOCKED_PROPERTY

Method Detail

createUser

changePassword

getUser

getUserByUuid

getUserByUsername

getUserByUsernameOrEmail

getUserByActivationKey

hasDuplicateUsername

getUsersByRole

saveUser

retireUser

unretireUser

purgeUser

purgeUser

getAllPrivileges

getAllRoles

saveRole

purgeRole

savePrivilege

purgePrivilege

getRole

getRoleByUuid

getPrivilege

getPrivilegeByUuid

getAllUsers

changePassword

changePassword

changeHashedPassword

changeQuestionAnswer

changeQuestionAnswer

getSecretQuestion

isSecretAnswer

getUsers

getUsersByName

getUsersByPerson

setUserProperty

removeUserProperty

generateSystemId

getUsers

getCountOfUsers

saveUserProperty

saveUserProperties

changePasswordUsingSecretAnswer

setUserActivationKey

changePasswordUsingActivationKey

getDefaultLocaleForUser

getLastLoginTime