Package com.appiancorp.suiteapi.personalization

Interface UserService

All Superinterfaces:
ContextSensitiveSingletonService, Service
public interface UserService extends ContextSensitiveSingletonService

Provides the main functionality needed to create, update, delete, and retrieve Users. Methods which retrieve users do not return deactivated users, unless noted otherwise.

For updating a user's password, authenticating a user, and creating a new user, the password must be provided in a hashed and base64 encoded byte[] using UTF-8 character-set. Use java.security.MessageDigest and org.apache.commons.codec.binary.Base64, for instance, to obtain the hashed form of a plaintext password in a base64 encoded byte[].

Methods of service classes can all throw the unchecked exception ServiceException if any system-level error (for example, server failure) occurs, and will in general throw a checked exception (InvalidXXXException) when an entity to be retrieved is inaccessible, instead of returning null. Exceptions to this paradigm (including the use of ResultList as described below) are noted. All checked exceptions extend AppianException.

It may be necessary to retrieve a subset of results as opposed to an entire collection, and also to sort the subset by some property of the returned object. "Paging" methods which return a ResultPage are provided in certain instances for this purpose. The ResultPage will contain the sorted subset of results (via Result.getResults()), and the total number of items in the available result set (via ResultPage.getAvailableItems()).

It may also be necessary to retrieve some results, even if all results cannot be retrieved (for instance, some of the entities corresponding to a list of entity IDs may no longer exist). Methods which return a ResultList are provided for this purpose. The Result.getResults() method in this case will return all results which can be retrieved. In addition, there will be a list of result codes (ResultList.getResultCodes()) that represent the successful retrieval of an entity, or, if the entity could not be retrieved, the reason for the failure. See the CODE_XXX constants in ResultList for details.

See Also:

  • Field Details

    • ACTION_SYSTEM_USER_CREATE

      static final Integer ACTION_SYSTEM_USER_CREATE
      Index in return array from getSystemActions(Integer[]) which refers to the user's permissions to create a user

    • ACTION_SYSTEM_USER_MODIFY_SECURITY_SETTINGS

      static final Integer ACTION_SYSTEM_USER_MODIFY_SECURITY_SETTINGS
      Index in return array from getSystemActions(Integer[]) which refers to the user's permissions to modify security settings of a group. This is not currently used.

    • ACTION_SYSTEM_GROUP_CREATE_PUBLIC

      static final Integer ACTION_SYSTEM_GROUP_CREATE_PUBLIC
      Index in return array from getSystemActions(Integer[]) which refers to the user's permissions to create a public group

    • ACTION_SYSTEM_GROUP_CREATE

      static final Integer ACTION_SYSTEM_GROUP_CREATE
      Index in return array from getSystemActions(Integer[]) which refers to the user's permissions to create a group

    • ACTION_SYSTEM_GROUPTYPE_CREATE_PUBLIC

      static final Integer ACTION_SYSTEM_GROUPTYPE_CREATE_PUBLIC
      Index in return array from getSystemActions(Integer[]) which refers to the user's permissions to create a public group type

    • ACTION_SYSTEM_GROUPTYPE_CREATE

      static final Integer ACTION_SYSTEM_GROUPTYPE_CREATE
      Index in return array from getSystemActions(Integer[]) which refers to the user's permissions to create a group type

    • ACTION_SYSTEM_VIEW_DEACTIVATED_USERS

      static final Integer ACTION_SYSTEM_VIEW_DEACTIVATED_USERS
      Index in return array from getSystemActions(Integer[]) which refers to the user's permissions to view deactivated users

    • ACTION_SYSTEM_GROUP_SET_DELEGATED_ADMIN_AT_GROUP_CREATION

      static final Integer ACTION_SYSTEM_GROUP_SET_DELEGATED_ADMIN_AT_GROUP_CREATION
      Index in return array from getSystemActions(Integer[]) which refers to the user's permissions to set if a group delegated admin at group creation

    • ACTION_USER_DELETE_USER

      static final Integer ACTION_USER_DELETE_USER
      Index in return array from getUserActions(String,Integer[]) which refers to the user's permissions to delete a user

    • ACTION_USER_EDIT_ALL_USER_ATTRIBUTES

      static final Integer ACTION_USER_EDIT_ALL_USER_ATTRIBUTES
      Index in return array from getUserActions(String,Integer[]) which refers to the user's permissions to edit all of a user's attributes

    • ACTION_USER_EDIT_LIMITED_USER_ATTRIBUTES

      static final Integer ACTION_USER_EDIT_LIMITED_USER_ATTRIBUTES
      Index in return array from getUserActions(String,Integer[]) which refers to the user's permissions to edit a user's limited attributes

    • ACTION_USER_VIEW_ALL_USER_ATTRIBUTES

      static final Integer ACTION_USER_VIEW_ALL_USER_ATTRIBUTES
      Index in return array from getUserActions(String,Integer[]) which refers to the user's permissions to view a user's attributes

    • ACTION_USER_VIEW_LIMITED_USER_ATTRIBUTES

      static final Integer ACTION_USER_VIEW_LIMITED_USER_ATTRIBUTES
      Index in return array from getUserActions(String,Integer[]) which refers to the user's permissions to view a user's limited attributes

    • ACTION_USER_VIEW_USER_EXISTENCE

      static final Integer ACTION_USER_VIEW_USER_EXISTENCE
      Index in return array from getUserActions(String,Integer[]) which refers to the user's permissions to see a user's existence

    • ACTION_USER_DEACTIVATE_USER

      static final Integer ACTION_USER_DEACTIVATE_USER
      Index in return array from getUserActions(String,Integer[]) which refers to the user's permissions to decativate a user

    • ACTION_USER_REACTIVATE_USER

      static final Integer ACTION_USER_REACTIVATE_USER
      Index in return array from getUserActions(String,Integer[]) which refers to the user's permissions to reactivate a user

    • createUser$UPDATES

      static final boolean createUser$UPDATES
      See Also:

    • createUsers$UPDATES

      static final boolean createUsers$UPDATES
      See Also:

    • updateUser$UPDATES

      static final boolean updateUser$UPDATES
      See Also:

    • updateUsers$UPDATES

      static final boolean updateUsers$UPDATES
      See Also:

    • getUser$UPDATES

      static final boolean getUser$UPDATES
      See Also:

    • getUsers$UPDATES

      static final boolean getUsers$UPDATES
      See Also:

    • getUserByUuid$UPDATES

      static final boolean getUserByUuid$UPDATES
      See Also:

    • getUsersByUuid$UPDATES

      static final boolean getUsersByUuid$UPDATES
      See Also:

    • findUsers$UPDATES

      static final boolean findUsers$UPDATES
      See Also:

    • findUsersForGroupType$UPDATES

      static final boolean findUsersForGroupType$UPDATES
      See Also:

    • findUsersForGroupPaging$UPDATES

      static final boolean findUsersForGroupPaging$UPDATES
      See Also:

    • isUserInGroupByRole$UPDATES

      static final boolean isUserInGroupByRole$UPDATES
      See Also:

    • authenticateUser$UPDATES

      static final boolean authenticateUser$UPDATES
      See Also:

    • authenticate$UPDATES

      static final boolean authenticate$UPDATES
      See Also:

    • changeUserPassword$UPDATES

      static final boolean changeUserPassword$UPDATES
      See Also:

    • doesUserExist$UPDATES

      static final boolean doesUserExist$UPDATES
      See Also:

    • isUsernameAvailable$UPDATES

      static final boolean isUsernameAvailable$UPDATES
      See Also:

    • getRankList$UPDATES

      static final boolean getRankList$UPDATES
      See Also:

    • getRankListForDisplay$UPDATES

      static final boolean getRankListForDisplay$UPDATES
      See Also:

    • createTitle$UPDATES

      static final boolean createTitle$UPDATES
      See Also:

    • updateTitle$UPDATES

      static final boolean updateTitle$UPDATES
      See Also:

    • getAllUserTypeAttributes$UPDATES

      static final boolean getAllUserTypeAttributes$UPDATES
      See Also:

    • getUserActions$UPDATES

      static final boolean getUserActions$UPDATES
      See Also:

    • getSystemActions$UPDATES

      static final boolean getSystemActions$UPDATES
      See Also:

    • isSocialSecurityNumberUnique$UPDATES

      static final boolean isSocialSecurityNumberUnique$UPDATES
      See Also:

    • isPasswordValid$UPDATES

      static final boolean isPasswordValid$UPDATES
      See Also:

    • isUserPasswordValid$UPDATES

      static final boolean isUserPasswordValid$UPDATES
      See Also:

    • reactivateUsers$UPDATES

      static final boolean reactivateUsers$UPDATES
      See Also:

    • deactivateUser$UPDATES

      static final boolean deactivateUser$UPDATES
      See Also:

    • deactivateUsers$UPDATES

      static final boolean deactivateUsers$UPDATES
      See Also:

    • getDeactivatedUsersPaging$UPDATES

      static final boolean getDeactivatedUsersPaging$UPDATES
      See Also:

    • findUsersPaging$UPDATES

      static final boolean findUsersPaging$UPDATES
      See Also:

    • getUsersForGroupByRolePaging$UPDATES

      static final boolean getUsersForGroupByRolePaging$UPDATES
      See Also:

    • isCurrentUserDeactivated$UPDATES

      static final boolean isCurrentUserDeactivated$UPDATES
      See Also:

    • getApplicationName$UPDATES

      static final boolean getApplicationName$UPDATES
      See Also:

    • getWorkspace$UPDATES

      static final boolean getWorkspace$UPDATES
      See Also:

    • getUsersList$UPDATES

      static final boolean getUsersList$UPDATES
      See Also:

    • findAllUsersPaging$UPDATES

      static final boolean findAllUsersPaging$UPDATES
      See Also:

    • updateUsernames$UPDATES

      static final boolean updateUsernames$UPDATES
      See Also:

    • commitUpdateUsernames$UPDATES

      static final boolean commitUpdateUsernames$UPDATES
      See Also:

    • rollbackUpdateUsernames$UPDATES

      static final boolean rollbackUpdateUsernames$UPDATES
      See Also:

    • suggestUsers$UPDATES

      static final boolean suggestUsers$UPDATES
      See Also:

    • searchUsersPaging$UPDATES

      static final boolean searchUsersPaging$UPDATES
      See Also:

    • suggestUsersBulk$UPDATES

      static final boolean suggestUsersBulk$UPDATES
      See Also:

    • reloadProperties$UPDATES

      static final boolean reloadProperties$UPDATES
      See Also:

    • validate$UPDATES

      static final boolean validate$UPDATES
      See Also:

    • addUserToFavorites$UPDATES

      static final boolean addUserToFavorites$UPDATES
      See Also:

    • removeUserFromFavorites$UPDATES

      static final boolean removeUserFromFavorites$UPDATES
      See Also:

    • getFavoriteUsers$UPDATES

      static final boolean getFavoriteUsers$UPDATES
      See Also:

    • suggest$UPDATES

      static final boolean suggest$UPDATES
      See Also:

    • loginAttempt$UPDATES

      static final boolean loginAttempt$UPDATES
      See Also:

    • unlockUser$UPDATES

      static final boolean unlockUser$UPDATES
      See Also:

    • isPasswordUnique$UPDATES

      static final boolean isPasswordUnique$UPDATES
      See Also:

    • setSecurityForUser$UPDATES

      static final boolean setSecurityForUser$UPDATES
      See Also:

    • getSecurityForUser$UPDATES

      static final boolean getSecurityForUser$UPDATES
      See Also:

    • renameUsersByUuid$UPDATES

      static final boolean renameUsersByUuid$UPDATES
      See Also:

  • Method Details

    • createUser

      String createUser(User user_) throws DuplicateNameException, InvalidNameException, InvalidSupervisorException, PrivilegeException, InvalidUserException
      Creates a new user

      The username field of the created user must be unique. User fields required for creation are: username, password.

      NOTES:

      1) The password field must be hashed to work properly with the the product interface.

      2)In order to minimize possible breaks with the user interface, it is HIGHLY recommended that the username be validated for illegal characters (only allow alphanumeric symbols, underscores, and periods).

      If, after a user is created, it is necessary to call any method using that user's UserServiceContext, then activateUserSession must be called on the following services:

      Parameters:
      user_ - a user to create
      Returns:
      the username of the user
      Throws:
      DuplicateNameException - if the username already exists
      InvalidNameException - if the username is null
      PrivilegeException - if the current user is not a System Administrator
      InvalidSupervisorException - if the supervisor property is neither null nor the login of a valid user
      InvalidUserException - if user_ is empty. This exception is also thrown if either the username or password field is empty.
      ServiceException - if any system-level error occurs

    • createUsers

      String[] createUsers(User[] users_) throws DuplicateNameException, InvalidNameException, InvalidSupervisorException, PrivilegeException, InvalidUserException
      Creates new users.

      The username field of the created user must be unique. User fields required for creation are: username.

      NOTES:

      1) Although this call will complete successfully if only the username field is populated, if the password field is not also populated the created user will not able to log into the application.

      2) The password field must be hashed to work properly with the the product interface.

      3)In order to minimize possible breaks with the user interface, it is HIGHLY recommended that the username be validated for illegal characters (only allow alphanumeric symbols, underscores, and periods).

      If, after a user is created, it is necessary to call any method using that user's UserServiceContext, then activateUserSession must be called on the following services:

      Parameters:
      users_ - users to create.
      Returns:
      the usernames of the users
      Throws:
      DuplicateNameException - if any of the usernames already exists
      InvalidNameException - if any username is null
      PrivilegeException - if the user is not a System Administrator Must be a System Administrator to create a user
      InvalidSupervisorException - if the supervisor property is not either null or the login of a valid user
      InvalidUserException - if null is passed for the object or the username or password are null
      ServiceException - if any system-level error occurs

    • updateUser

      void updateUser(User user_) throws InvalidUserException, InvalidSupervisorException, PrivilegeException
      Updates a user. Does not modify username or passwordfields. You can also pass in a UserProfile to update fields not contained within User.

      If you do not pass in a UserProfile, the additional fields that are in UserProfile but not in User will be erased.

      In order to minimize possible breaks with the user interface, it is HIGHLY recommended that the username field be validated for illegal characters (only allow alphanumeric symbols and underscores).

      This method will ignore any changes to the properties userTypeId and userTypeName when applied to the 'Administrator' user.

      Parameters:
      user_ - the user to modify
      Throws:
      InvalidUserException - if null is passed for the object or the username or password are null
      InvalidSupervisorException - if the supervisor property is neither null nor the login of a valid user
      ServiceException - if any system-level error occurs
      PrivilegeException
      See Also:

    • updateUsers

      void updateUsers(User[] users_) throws InvalidUserException, InvalidSupervisorException, PrivilegeException
      Updates users. Does not modify username or passwordfields. You can also pass in an array of UserProfile objects to update fields not contained within User.

      If you do not pass in UserProfile objects, the additional fields that are in UserProfile but not in User will be erased.

      In order to minimize possible breaks with the user interface, it is HIGHLY recommended that the username field be validated for illegal characters (only allow alphanumeric symbols and underscores).

      This method will ignore any changes to the properties userTypeId and userTypeName when applied to the 'Administrator' user.

      Parameters:
      users_ - users to update
      Throws:
      InvalidUserException - if any user with a given username does not exist
      InvalidSupervisorException - if the supervisor property is neither null nor the login of a valid user
      ServiceException - if any system-level error occurs
      PrivilegeException
      See Also:

    • getUser

      User getUser(String username_) throws InvalidUserException
      Gets a single user by username
      Parameters:
      username_ - the primary key of a user
      Returns:
      the User
      Throws:
      InvalidUserException - if a user with the given username does not exist
      ServiceException - if any system-level error occurs

    • getUsers

      User[] getUsers(String[] usernames_) throws InvalidUserException
      Gets a list of users by username.
      Parameters:
      usernames_ - usernames of users to retrieve
      Returns:
      a list of users corresponding to the given usernames
      Throws:
      InvalidUserException - if any user with the a given username does not exist
      ServiceException - if any system-level error occurs

    • getUserByUuid

      User getUserByUuid(@ConvertWith(com.appiancorp.kougar.mapper.parameters.UuidParameterConverter.class) String uuid) throws InvalidUserException
      Gets a single user by uuid
      Parameters:
      uuid - the uuid of a user
      Returns:
      the User
      Throws:
      InvalidUserException - if a user with the given uuid does not exist
      ServiceException - if any system-level error occurs

    • getUsersByUuid

      User[] getUsersByUuid(@ConvertWith(com.appiancorp.kougar.mapper.parameters.UuidParameterConverter[][].class) String[] uuids) throws InvalidUserException
      Gets a list of users by uuid.
      Parameters:
      uuids - uuids of users to retrieve
      Returns:
      a list of users corresponding to the given uuids
      Throws:
      InvalidUserException - if any user with the a given uuid does not exist
      ServiceException - if any system-level error occurs

    • findUsers

      @Deprecated User[] findUsers(UserSearch userSearch_, boolean caseSensitive_) throws UnsupportedOperatorException
      Deprecated.
      use findUsersPaging
      Finds a list of users for a given search criteria.

      The userSearch_ object should be populated with the user fields to be searched on, and the criteria to be used in performing the search. For example, the userSearch_ might have the username field set to "john.doe", the lastName fields set to "Doe", the operatorUsername field set to Operator.EQUALS and the operatorLastName field set to Operator.ENDS_WITH. Such a search will return all users whose username is "john.doe", and whose last name ends with "Doe". To get all users, use findAllUsersPaging.

      See GroupTypeService.getOperatorsForDataType(int) to obtain a list of possible operators for a given data type.

      Parameters:
      userSearch_ - the search criteria
      caseSensitive_ - whether the search is case sensitive
      Returns:
      the users that meet the given search criteria
      Throws:
      UnsupportedOperatorException - if userSearch_ contains an invalid operator
      ServiceException - if any system-level error occurs

    • findUsersForGroupType

      @Deprecated User[] findUsersForGroupType(UserSearch userSearch_, boolean caseSensitive_, Long groupTypeId_) throws UnsupportedOperatorException, InvalidGroupTypeException
      Deprecated.
      Use findUsersForGroupPaging(UserSearch, boolean, Long, int, int, Integer, Integer)
      Finds a list of users who are members of groups of a certain group type, for a given search criteria.

      This method behaves in a similar fashion to findUsers(UserSearch, boolean), except that it only searches for users in groups with the given group type.

      Parameters:
      userSearch_ - the search criteria
      caseSensitive_ - whether the search is case sensitive
      groupTypeId_ - groupType to find users who are members of
      Returns:
      the users that meet the given search criteria
      Throws:
      UnsupportedOperatorException - if userSearch_ contains an invalid operator
      InvalidGroupTypeException - if the group type does not exist
      ServiceException - if any system-level error occurs

    • findUsersForGroupPaging

      ResultPage findUsersForGroupPaging(UserSearch searchCriteria_, boolean caseSensitive_, Long groupId_, int startIndex_, int batchSize_, Integer sortProperty_, Integer sortOrder_) throws InvalidGroupException, UnsupportedOperatorException
      Finds users who are members of a certain group for a given search criteria.

      This method behaves in a similar fashion to findUsers(UserSearch, boolean), except that it only searches for users in the given group.

      Parameters:
      searchCriteria_ - the search criteria
      caseSensitive_ - whether the search is case sensitive
      groupId_ - the ID of the group in which to search
      startIndex_ - the index into the collection of total results at which to start. Negative numbers are treated as zeros.
      batchSize_ - the number of results to return. use of Constants.COUNT_ALL will result in the entire collection being returned, but this is STRONGLY discouraged.
      sortProperty_ - the property by which the results will be sorted This is one of the SORT_BY_XXX constants in UserProfile
      sortOrder_ - Constants.SORT_ORDER_ASCENDING for sorting results in ascending order, Constants.SORT_ORDER_DESCENDING for sorting results in descending order
      Returns:
      ResultPage of User objects.
      Throws:
      InvalidGroupException - if the group does not exist
      UnsupportedOperatorException - if userSearch_ contains an invalid operator
      ServiceException - if any system-level error occurs

    • isUserInGroupByRole

      boolean isUserInGroupByRole(String username_, Long groupId_, Integer role_) throws InvalidUserException, InvalidGroupException, UnsupportedRoleException
      Checks if a user has the given role for the given group
      Parameters:
      username_ - the login of the user
      groupId_ - the group whose membership is being checked
      role_ - the role being checked. This must be one of the USER_ROLE_XXX constants in User
      Returns:
      whether the user has the given role for the group
      Throws:
      InvalidUserException - if the user does not exist
      InvalidGroupException - if the group does not exist
      UnsupportedRoleException - if the role is invalid
      ServiceException - if any system-level error occurs

    • authenticateUser

      @Deprecated UserProfile authenticateUser(String username_, String password_) throws InvalidLoginException
      Deprecated.
      Since 6.0.2, use authenticate(String, byte[])
      Used to validate a user (the login mechanism). Note: If password is stored as hashed in database (stored as hashed by default in the product), the password passed in to this function must be hashed. For more details, see topic "Frequently Asked Questions" in the product Developer's Guide.
      Parameters:
      username_ - the login of the user
      password_ - the password of the user
      Returns:
      the user matching the login
      Throws:
      InvalidLoginException - if no user with the given username and password exists
      ServiceException - if any system-level error occurs

    • authenticate

      UserProfile authenticate(String username, byte[] password) throws InvalidLoginException
      Used to authenticate the user as part of the login mechanism. A user that provides the correct credentials, a username and password combination that match those stored in the system, is considered to be authenticated. Note: this method will successfully authenticate regardless of whether or not the password is temporary (see changeUserPassword(String, byte[], boolean)).
      Parameters:
      username - the username of the user to authenticate
      password - the user's hashed password; see the interface description above.
      Returns:
      the authenticated user
      Throws:
      InvalidLoginException - if the authentication challenge fails with the provided credentials

    • changeUserPassword

      void changeUserPassword(String username, byte[] newPassword, boolean temporary) throws InvalidUserException, PrivilegeException
      Change the user's password to the new provided password. The provided password must be in its hashed form. If the temporary flag is passed as true, the user will be required to change their password on the next login.
      Parameters:
      username - the username of the user whose password is being changed
      newPassword - the new password, hashed; see interface description above for more info
      temporary - a flag to indicate whether this is a temporary password that should be reset the next time the user logs in
      Throws:
      InvalidUserException - if the provided username doesn't map to a user in the system or the user is deactivated
      PrivilegeException - if the method is called by a user other than a System Administrator or the user whose password the method is attempting to change Used to change a user's password

    • doesUserExist

      boolean doesUserExist(String username_)
      Determines whether a user with the exact username exists by conducting a case-sensitive comparison of the given username to usernames in the system. Users cannot be created with a username that matches an existing username in a case-insensitive comparison, so use isUsernameAvailable(String) instead to determine if a given username is available for use when creating a new user.
      Parameters:
      username_ - the username
      Returns:
      true, if a user with this username exists.
      Throws:
      ServiceException - if any system-level error occurs

    • isUsernameAvailable

      boolean isUsernameAvailable(String username)
      Determines whether the given username is available for use. A username is available if it does not match any existing username in a case-insensitive comparison.
      Parameters:
      username_ - the username
      Returns:
      true, if a new user can be created with this username.

    • getRankList

      UserRank[] getRankList()
      Gets the list of ranks (titles) used in the system
      Returns:
      the rank list
      Throws:
      ServiceException - if any system-level error occurs

    • getRankListForDisplay

      UserRank[] getRankListForDisplay()
      Gets the list of ranks (titles) used in the system for display purposes as well as a rank of "Any"
      Returns:
      the rank list
      Throws:
      ServiceException - if any system-level error occurs

    • createTitle

      Long createTitle(UserRank title_) throws PrivilegeException
      Creates a new rank (title). Only the name is required.
      Returns:
      the new rank (title) id
      Throws:
      PrivilegeException - if the user context is not a system administrator
      NullPointerException - if the argument itself is null (title_ is null)

    • updateTitle

      void updateTitle(UserRank title_) throws PrivilegeException, InvalidTitleException
      Updates the rank (title) name associated with the id of the object passed as a parameter
      Throws:
      InvalidTitleException - if the passed title (rank) id does not exist or is null
      PrivilegeException - if the user context is not a system administrator
      NullPointerException - if the argument itself is null (title_ is null)

    • getAllUserTypeAttributes

      Attribute[] getAllUserTypeAttributes()
      Gets the list of user type attributes - the fields which can be used in user rules.
      Returns:
      the attribute list
      Throws:
      ServiceException - if any system-level error occurs

    • getUserActions

      Boolean[] getUserActions(String username_, Integer[] actionIds_) throws InvalidUserException, PrivilegeException
      Gets boolean values indicating whether the user can perform the action with the given ID. The user must be a basic user; to check the actions that a system administrator can perform, use getSystemActions(Integer[])
      Parameters:
      username_ - the username of the user
      actionIds_ - IDs of actions for which to check the user's permissions. Each action ID must be one of the ACTION_USER_XXX constants
      Returns:
      an array that is parallel to actionIds_, with each element in the result set to true if the user can perform the associated action
      Throws:
      InvalidUserException - if the user does not exist
      PrivilegeException
      ServiceException - if any system-level error occurs

    • getSystemActions

      Boolean[] getSystemActions(Integer[] actionIds_)
      Gets boolean values indicating whether a system administrator user can perform the action with the given ID.
      Parameters:
      actionIds_ - IDs of system actions. Each action ID must be one of the ACTION_SYSTEM_XXX constants
      Returns:
      an array parallel to actionIds_, with each element in the result set to true if the user can perform the associated action
      Throws:
      ServiceException - if any system-level error occurs

    • isSocialSecurityNumberUnique

      boolean isSocialSecurityNumberUnique(String socialSceurityNumber_)
      Determines whether a user with the given social security number already exists
      Parameters:
      socialSceurityNumber_ - a social security number, in XXXXXXXXX format
      Returns:
      true if no current user has this social security number
      Throws:
      ServiceException - if any system-level error occurs

    • isPasswordValid

      @Deprecated boolean isPasswordValid(String username_, String password_) throws InvalidUserException, PrivilegeException
      Deprecated.
      Since 6.0.2, use isUserPasswordValid(String, byte[])
      Validates password for a given user. Simply checks if entered password for given user matches his stored password.
      Parameters:
      username_ - the login of a user
      password_ - the password of the user
      Returns:
      true if password is valid
      Throws:
      InvalidUserException - if the user does not exist
      ServiceException - if any system-level error occurs
      PrivilegeException

    • isUserPasswordValid

      boolean isUserPasswordValid(String username, byte[] password) throws InvalidUserException, PrivilegeException
      Validates that the provided password matches that of the given user. The password must be provided in its hashed form. See the interface description above.
      Parameters:
      username - the username of the user to check
      password - the hashed password to check
      Returns:
      true if the password is the user's current password, otherwise false
      Throws:
      InvalidUserException - if the provided username doesn't map to a user in the system or the user is deactivated
      PrivilegeException

    • reactivateUsers

      void reactivateUsers(String[] userNames_) throws InvalidUserException, PrivilegeException
      Reactivates the given Users.
      Parameters:
      userNames_ - the logins of users that are inactive
      Throws:
      InvalidUserException - if any of the logins does not correspond to a valid user
      PrivilegeException - if the current user is not an admin
      ServiceException - if any system-level error occurs

    • deactivateUser

      void deactivateUser(String userName_) throws InvalidUserException, PrivilegeException
      Deactivates the given User. Deactivating a user does NOT wipe the user from the system, but rather disables the user's ability to log into the system and other users' ability to view the user. A deactivated user can always be reactivated using reactivateUsers(String[]).
      Parameters:
      userName_ - the login of a user to deactivate
      Throws:
      InvalidUserException - if the login does not correspond to a valid user or the Administrator was provided
      PrivilegeException - if the current user is not an admin
      ServiceException - if any system-level error occurs

    • deactivateUsers

      void deactivateUsers(String[] userNames_) throws InvalidUserException, PrivilegeException
      Deactivates the given Users. Deactivating a user does NOT wipe the user from the system, but rather disables the user's ability to log into the system and other users' ability to view the user. A deactivated user can always be reactivated using reactivateUsers(String[]).
      Parameters:
      userNames_ - the logins of a users to deactivate
      Throws:
      InvalidUserException - if one of the logins does not correspond to a valid user or the Administrator is in the list of users to deactivate
      PrivilegeException - if the current user is not an admin
      ServiceException - if any system-level error occurs

    • getDeactivatedUsersPaging

      ResultPage getDeactivatedUsersPaging(int startIndex_, int batchSize_, Integer sortProperty_, Integer sortOrder_)
      Returns all the deactivated users.
      Parameters:
      startIndex_ - the index into the collection of total results at which to start. Negative numbers are treated as zeros.
      batchSize_ - the number of results to return. use of Constants.COUNT_ALL will result in the entire collection being returned, but this is STRONGLY discouraged.
      sortProperty_ - the property by which the results will be sorted This is one of the SORT_BY_XXX constants in UserProfile
      sortOrder_ - Constants.SORT_ORDER_ASCENDING for sorting results in ascending order, Constants.SORT_ORDER_DESCENDING for sorting results in descending order
      Returns:
      a ResultPage containing an array of User objects corresponding to inactive users
      Throws:
      ServiceException - if any system-level error occurs

    • findUsersPaging

      ResultPage findUsersPaging(UserSearch userSearch_, boolean caseSensitive_, int startIndex_, int batchSize_, Integer sortProperty_, Integer sortOrder_) throws UnsupportedOperatorException
      Returns all users who match the search criteria.

      This method will return the paged resultset corresponding to findUsers(UserSearch, boolean)

      Parameters:
      userSearch_ - criteria for the search
      caseSensitive_ - whether the search is case sensitive
      startIndex_ - the index into the collection of total results at which to start. Negative numbers are treated as zeros.
      batchSize_ - the number of results to return. use of Constants.COUNT_ALL will result in the entire collection being returned, but this is STRONGLY discouraged.
      sortProperty_ - the property by which the results will be sorted This is one of the SORT_BY_XXX constants in User
      sortOrder_ - Constants.SORT_ORDER_ASCENDING for sorting results in ascending order, Constants.SORT_ORDER_DESCENDING for sorting results in descending order
      Returns:
      a ResultPage containing an array of User objects correpsonding to users who match the search criteria
      Throws:
      UnsupportedOperatorException - if userSearch_ contains an invalid operator
      ServiceException - if any system-level error occurs

    • getUsersForGroupByRolePaging

      ResultPage getUsersForGroupByRolePaging(Long groupId_, Integer role_, int startIndex_, int batchSize_, Integer sortProperty_, Integer sortOrder_) throws InvalidGroupException, UnsupportedRoleException, PrivilegeException
      Returns all users in the given group with the given role.
      Parameters:
      groupId_ - the ID of the group
      role_ - the role. This is one of the USER_ROLE_XXX constants in User
      startIndex_ - the index into the collection of total results at which to start. Negative numbers are treated as zeros.
      batchSize_ - the number of results to return. use of Constants.COUNT_ALL will result in the entire collection being returned, but this is STRONGLY discouraged.
      sortProperty_ - the property by which the results will be sorted This is one of the SORT_BY_XXX constants in User
      sortOrder_ - Constants.SORT_ORDER_ASCENDING for sorting results in ascending order, Constants.SORT_ORDER_DESCENDING for sorting results in descending order
      Returns:
      a ResultPage containing an array of User beans corresponding to users who match the search criteria
      Throws:
      InvalidGroupException - if the group id does not exist
      UnsupportedRoleException - if the role is invalid
      PrivilegeException - if the user calling this method does not have sufficient privileges to view the members of this group - that is, if GroupService.getGroupActions(Long, Integer[]) returns false for the action GroupService.ACTION_GROUP_VIEW_GROUP_MEMBERS
      ServiceException - if any system-level error occurs

    • isCurrentUserDeactivated

      boolean isCurrentUserDeactivated()
      Determines whether the current user is deactivated
      Returns:
      true if the current user is deactivated
      Throws:
      ServiceException - if any system-level error occurs

    • getApplicationName

      String getApplicationName()
      Gets the name of the application on which this service is running.
      Returns:
      the name of the application
      Throws:
      ServiceException - if any system-level error occurs

    • getWorkspace

      String[] getWorkspace()
      Gets the current memory profile for the workspace.
      Returns:
      array of Strings of length 4 describing memory usage:
      • [0]Used - Memory Used by the Server so far for storage
      • [1]Allocated - Memory allocated for use. Often if a large data item was allocated by a server and subsequently freed, this value will be large compared to "Used". If nearly all memory allocated is in use, this value will be close to (but always higher than) "Used"
      • [2]Mapped - is the space used by memory-mapped files
      • [3]Available - is the total available memory for the Server process
      Note: All usage statistics are in Bytes.
      Throws:
      ServiceException - if any system-level error occurs

    • getUsersList

      ResultList getUsersList(String[] usernames)
      Retrieves the users by username without throwing exceptions.

      The result codes returned in the ResultList are in the same order and correspond to the usernames passed as the parameter. The following result codes are returned:

      The User array returned in the results is neither the same length as the input array nor is it in the same order. Any invalid usernames have no corresponding item in the array and users that cannot be viewed by the context users are sorted to the end of the array for convenience.
      Parameters:
      usernames - the usernames of the users to retrieve
      Returns:
      a ResultList containing the an array of User objects and result codes corresponding to the input array.
      Throws:
      ServiceException - if any system-level error occurs

    • findAllUsersPaging

      ResultPage findAllUsersPaging(boolean caseSensitive_, int startIndex_, int batchSize_, Integer sortProperty_, Integer sortOrder_)
      Fast method that gets all users.
      Parameters:
      startIndex_ - the index into the collection of total results at which to start. Negative numbers are treated as zeros.
      batchSize_ - the number of results to return. use of Constants.COUNT_ALL will result in the entire collection being returned, but this is STRONGLY discouraged.
      sortProperty_ - the property by which the results will be sorted This is one of the SORT_BY_XXX constants in UserProfile
      sortOrder_ - Constants.SORT_ORDER_ASCENDING for sorting results in ascending order, Constants.SORT_ORDER_DESCENDING for sorting results in descending order
      Returns:
      a ResultPage containing an array of User objects
      Throws:
      ServiceException - if any system-level error occurs

    • updateUsernames

      @Deprecated void updateUsernames(String[] oldUsernames_, String[] newUsernames_, long maxExpirationTimeInSeconds_) throws IllegalArgumentException, DuplicateNameException
      Deprecated.
      instead use renameUsersByUuid(java.lang.String[], java.lang.String[])
      DEPRECATED: See renameUsersByUuid(java.lang.String[], java.lang.String[]) Updates a list of old usernames to new usernames.

      If successful, this method must be followed by commitUpdateUsernames(). After commitUpdateUsernames has been called, the old usernames will still be active, but will expire after the interval specified by maxExpirationTimeInSeconds_; if updateUsernames is successful but commitUpdateUsernames is not called, the new usernames will not become active.

      If unsuccessful, this method should be followed by rollbackUpdateUsernames(). This will simply free memory dedicated to mapping old usernames to new usernames.

      Parameters:
      oldUsernames_ - the usernames to be updated
      newUsernames_ - the usernames to which the old usernames will be updated
      maxExpirationTimeInSeconds_ - the interval, in seconds, after commitUpdateUsernames has been called, after which the old usernames will expire. If this parameter is zero or a negative value the old usernames will expire instantly. After expiration, the old usernames will no longer be valid.
      Throws:
      IllegalArgumentException - if the length of oldUsernames_ is not the same as the length of newUsernames_
      DuplicateNameException - if any oldUsernames_ or newUsernames_ contain any duplicates, or if an old username is being updated to a username that already exists
      ServiceException - if any system-level error occurs

    • commitUpdateUsernames

      @Deprecated void commitUpdateUsernames()
      Deprecated.
      instead use renameUsersByUuid(java.lang.String[], java.lang.String[])
      DEPRECATED: See renameUsersByUuid(java.lang.String[], java.lang.String[]) Commits an update of usernames.

      This method should be preceded by a call to updateUsernames(String[], String[], long). After the commit, the old usernames will be temporarily active, and will expire after the interval specified by maxExpirationTimeInSeconds_; if commitUpdateUsernames is not called, the new usernames will not become active.

      Throws:
      ServiceException - if any system-level error occurs

    • rollbackUpdateUsernames

      @Deprecated void rollbackUpdateUsernames()
      Deprecated.
      instead use renameUsersByUuid(java.lang.String[], java.lang.String[])
      DEPRECATED: See renameUsersByUuid(java.lang.String[], java.lang.String[]) Rolls back an update of usernames.

      This method should be called if updateUsernames(String[], String[], long) is unsuccessful. The rollback will simply free memory dedicated to mapping old usernames to new usernames.

      Throws:
      ServiceException - if any system-level error occurs

    • suggestUsers

      @Deprecated String suggestUsers(String query_, int maxSuggestions_)
      Deprecated.
      use suggest(String, int, SuggestParam[], Boolean) instead
      Returns a String in a specified format that contains Users whose first, last, or username match or partially match the query string. The number of suggestions is limited. Format (for Users and Groups: [[4, 'john.user', John User],[5, 32, 'Finance']]
      Parameters:
      query_ - The search query.
      maxSuggestions_ - The maximum number of suggestions to return.
      Returns:
      A String of suggestions in the specified format.

    • searchUsersPaging

      ResultPage searchUsersPaging(String query_, int startIndex_, int batchSize_, Integer sortProperty_, Integer sorOrder_)
      Searches for Users by first, last, and username.
      Parameters:
      query_ - The query by which to search for Users.
      startIndex_ - the index into the collection of total results at which to start. Negative numbers are treated as zeros.
      batchSize_ - the number of results to return. Use Constants.COUNT_ALL to return the entire collection, but this is STRONGLY discouraged.
      sortProperty_ - the property by which the results will be sorted. This is one of the SORT_BY_XXX constants in User.
      sortOrder_ - the order in which to sort the results. This is one of Constants.SORT_ORDER_ASCENDING or Constants.SORT_ORDER_DESCENDING
      Returns:
      A ResultPage of User objects which match the search query.

    • suggestUsersBulk

      @Deprecated Suggestion[][] suggestUsersBulk(String[] queries_, int maxSuggestionsPerQuery_)
      Deprecated.
      use suggest(String, int, SuggestParam[], Boolean) instead
      Suggests Users whose first, last, or username matches each query.
      Parameters:
      queries_ - A list of queries by which to search for Users.
      maxSuggestionsPerQuery_ - The maximum number of suggestions to return for each query.
      Returns:
      An array of Suggestion[] which are the suggestions corresponding to each query string. The first dimension of the array is equal to the number of queries passed to the method. The second dimension is equal to or lesser than the max suggestion per query.

    • reloadProperties

      @Deprecated void reloadProperties()
      Deprecated.
      reloading properties is now automatic, so this call is now unnecessary and does nothing.
      Reloads all database-level properties files (*.xml, *.properties) without interrupting API services
      Throws:
      ServiceException - if any system-level error occurs

    • validate

      String validate()
      Runs validation tests against the database to check whether it is corrupt, and returns a line-separated list of validation results
      Returns:
      the validation results
      Throws:
      ServiceException - if any system-level error occurs

    • addUserToFavorites

      void addUserToFavorites(String username_) throws InvalidUserException, PrivilegeException
      Adds this user (username_) to the current user's favorites
      Parameters:
      username_ - The username of the user that is to be added as favorites
      Throws:
      InvalidUserException - if username_ is empty, or the username_ does not exist
      PrivilegeException

    • removeUserFromFavorites

      void removeUserFromFavorites(String username_) throws InvalidUserException
      Removes this user (username_) from the current user's favorites
      Parameters:
      username_ - The username of the user that is to be removed from favorites
      Throws:
      InvalidUserException - if username_ is empty or the username_ does not exist

    • getFavoriteUsers

      ResultPage getFavoriteUsers(int startIndex_, int batchSize_, Integer sortProperty_, Integer sortOrder_)
      Returns favorite users of the current user
      Parameters:
      startIndex_ - the index into the collection of total results at which to start. Negative numbers are treated as zeros.
      batchSize_ - the number of results to return. Use Constants.COUNT_ALL to return the entire collection, but this is STRONGLY discouraged.
      sortProperty_ - the property by which the results will be sorted. This is one of the SORT_BY_XXX constants in User.
      sortOrder_ - the order in which to sort the results. This is one of Constants.SORT_ORDER_ASCENDING or Constants.SORT_ORDER_DESCENDING
      Returns:
      A ResultPage of User objects

    • suggest

      String suggest(String query, int maxItems, SuggestParam[] params, Boolean groupResults)
      Parameters:
      query -
      maxItems -
      params - list of information on what is being suggested and what format the results should be in. valid types are user.
      groupResults - if specifying more than one SuggestParam, would you like to group the results by type, or mixed together and sorted? Default is true. If grouped, order of types matches the order of the suggestParams passed in.
      Returns:
      a JSON formatted string

    • suggest

      String suggest(String query, int maxItems, SuggestParam[] params, Boolean groupResults, Long[] allowList)
      Parameters:
      query -
      maxItems -
      params - list of information on what is being suggested and what format the results should be in. valid types are user.
      groupResults - if specifying more than one SuggestParam, would you like to group the results by type, or mixed together and sorted? Default is true. If grouped, order of types matches the order of the suggestParams passed in.
      allowList - list of IDs that will be automatically added to returned results, filtered by query. Ignored if null or empty.
      Returns:
      a JSON formatted string

    • loginAttempt

      @Deprecated boolean loginAttempt(boolean valid)
      Deprecated.
      Use loginAttempt(String, boolean) instead.
      Increases the number of login attempts a user has tried. The user making this call is the user which the attempts are increased to.
      Parameters:
      valid - Whether the login attempt is successful or not
      Returns:
      true if the user is allowed to login. False if the user is locked

    • loginAttempt

      boolean loginAttempt(String username, boolean valid)
      Increases the number of login attempts a user has tried.
      Parameters:
      username - The user attempting the login
      valid - Whether the login attempt is successful or not
      Returns:
      true if the user is allowed to login. False if the user is locked

    • unlockUser

      void unlockUser(String username) throws InvalidUserException, PrivilegeException
      Unlocks a user that has reached the maximum number of attempts and the lockout duration has not expired yet.
      Parameters:
      username - the username
      Throws:
      InvalidUserException - if the provided username doesn't map to a user in the system or the user is deactivated
      PrivilegeException - if the method is called by a user other than a System Administrator

    • isPasswordUnique

      boolean isPasswordUnique(String username, byte[] password) throws PrivilegeException, InvalidUserException
      Checkes whether the given user's password is not one of their last N passwords, where N is a number determined by the conf.security.pw.NUMBER_PAST_PASSWORDS_TO_CHECK in custom.properties. This method should be used in conjunction with changeUserPassword(String, byte[], boolean) for systems that need to enforce that a new password is not one of the previous passwords. The provided password must be hashed using the algorithm. See the interface description above.
      Parameters:
      username - the user whose password history should be checked
      password - the hashed password to check against the history
      Returns:
      true if the password is unique, otherwise false.
      Throws:
      PrivilegeException - if the method is called by a user other than a System Administrator or the user for whom the method is attempting to verify the new password for uniqueness
      InvalidUserException

    • setSecurityForUser

      void setSecurityForUser(String username, Security sec) throws PrivilegeException, InvalidUserException, InvalidGroupException
      Sets the security settings of the user. Fields canInherit, inheritable and doesInherit will be ignored
      Parameters:
      username - the user whose security settings will be set
      sec - a Security object which encapsulates the security settings for a user. The role map in the Security object must be a RoleMap object.
      Throws:
      PrivilegeException - if the current user does not have sufficient privileges to perform this operation or cannot see a group specified in the rolemap
      InvalidUserException - if the user specified in the rolemap is invalid or the current user does not have viewing privileges over that user
      InvalidGroupException - if the group specified in the rolemap is invalid

    • getSecurityForUser

      Security getSecurityForUser(String username) throws PrivilegeException
      Gets the security settings of the user.
      Parameters:
      username - the user whose security settings will be retrieved
      Returns:
      the Security object that contains the security for the user. The role map in the Security object is a RoleMap object.
      Throws:
      PrivilegeException - if the current user does not have sufficient privileges to perform this operation

    • renameUsersByUuid

      void renameUsersByUuid(@ConvertWith(com.appiancorp.kougar.mapper.parameters.UuidParameterConverter[][].class) String[] usernameUuids, String[] newUsernames) throws AppianRuntimeException
      Rename users at usernameUuids to newUsernames. This replaces the previous updateUsernames/commitUpdateUsernames/rollbackUpdateUsernames for each engine. This generates a request to all enlisted components of the Appian system to do the rename. It is transactional, and will be retried as necessary if a component is down at the time. Renaming by UUID is idempotent, so it may be retried as necessary if a component is down during the attempt. The rename is done immediately on the Personalization K engine (which is the primary source of truth for users). It may or may not be done immediately on other engines and other persistent storage mechanisms attached in a structured manner to Appian. A timeout may be employed to allow the method to return quickly, even if an engine is down at the time of the attempt. Such engines may be retried later automatically. All user creation and user renames are sequenced, such that they occur in order even when components are down. Invoking user must have privilege to reactivate user.
      Parameters:
      usernameUuids - must be non-null, match newUsernames in length, be unique, contain no nulls (may use getUserUuids to obtain this information) The UUID is used to avoid ambiguous behaviors when renaming users in a loop, e.g., (a->b, b->c, c->a), which would have race conditions between distributed engines holding the data. Use of the user UUID avoids the ambiguity.
      newUsernames - must be non-null, match usernameUuids in length, be unique, contain no nulls, be valid usernames (see instead use createUser(User))
      Throws:
      DuplicateNameException
      InvalidNameException
      PrivilegeException
      InvalidUserException
      SelfRenameException
      AppianRuntimeException