Package com.appiancorp.suiteapi.personalization

Interface UserProfileService

All Superinterfaces:
ContextSensitiveSingletonService, Service
public interface UserProfileService extends ContextSensitiveSingletonService

Provides the main functionality needed to create, update, delete, and retrieve UserProfile objects from the Personalization service.

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

  • Method Details

    • getUser

      UserProfile getUser(String username_) throws InvalidUserException
      Gets a single user by username.
      Parameters:
      username_ - the unique username of the user
      Returns:
      a UserProfile corresponding to the username_
      Throws:
      InvalidUserException - if the given username does correspond to a valid user
      ServiceException - if any system-level error occurs

    • getUsers

      UserProfile[] getUsers(String[] usernames_) throws InvalidUserException
      Retrieves a list of users by username.
      Parameters:
      usernames_ - the unique usernames of the users objects
      Returns:
      an array of UserProfile objects corresponding to the usernames_
      Throws:
      InvalidUserException - if a given username does not exist
      ServiceException - if any system-level error occurs

    • getUserByUuid

      UserProfile getUserByUuid(@ConvertWith(com.appiancorp.kougar.mapper.parameters.UuidParameterConverter.class) String uuid) throws InvalidUserException
      Gets a single user by uuid.
      Parameters:
      uuid - the unique uuid of the user
      Returns:
      a UserProfile corresponding to the uuid
      Throws:
      InvalidUserException - if the given uuid does correspond to a valid user
      ServiceException - if any system-level error occurs

    • getUsersByUuid

      UserProfile[] getUsersByUuid(@ConvertWith(com.appiancorp.kougar.mapper.parameters.UuidParameterConverter[][].class) String[] uuids) throws InvalidUserException
      Retrieves a list of users by uuid.
      Parameters:
      uuids - the unique uuids of the users objects
      Returns:
      an array of UserProfile objects corresponding to the uuids
      Throws:
      InvalidUserException - if a given uuid does not correspond to a valid user
      ServiceException - if any system-level error occurs

    • getUsersCreation

      Timestamp[] getUsersCreation(String[] usernames) throws InvalidUserException
      Gets the users creation date
      Parameters:
      usernames - The list of users
      Returns:
      An array of timestamps with the user creation date.
      Throws:
      InvalidUserException

    • getUsersForGroupByRolePaging

      @Deprecated UserProfile[] getUsersForGroupByRolePaging(Long groupId_, int role_, int startIndex_, int batchSize_, Integer sortProperty_, Integer sortOrder_) throws InvalidGroupException, UnsupportedRoleException
      Deprecated.
      Use UserService.getUsersForGroupByRolePaging(Long, Integer, int, int, Integer, Integer)
      Retrieves a list of users for a given group by user role.
      Parameters:
      groupId_ - ID of the group whose users should be retrieved
      role_ - the role for which to retrieve users. Valid roles are 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 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 UserProfile.
      sortOrder_ - the order in which to sort the results. This is one of Constants.SORT_ORDER_ASCENDING or Constants.SORT_ORDER_DESCENDING
      Returns:
      an array of UserProfile objects corresponding to the users in the group with the given role
      Throws:
      InvalidGroupException - if the group given by groupId_ 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).
      Parameters:
      username_ - the unique username of a user
      password_ - the password for the user
      Returns:
      the UserProfile of the user with the given username
      Throws:
      InvalidLoginException - if the given username_ and password_ are not those of a valid user
      ServiceException - if any system-level error occurs

    • findUsers

      @Deprecated UserProfile[] findUsers(UserSearch userSearch_, boolean caseSensitive_) throws UnsupportedOperatorException
      Deprecated.
      Use findUsersPaging(UserSearch, boolean, int, int, Integer, Integer) instead.
      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".

      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

    • findUsersPaging

      ResultPage findUsersPaging(UserSearch userSearch_, boolean caseSensitive_, int startIndex_, int batchSize_, Integer sortProperty_, Integer sortOrder_) throws UnsupportedOperatorException
      Finds a list of users for a given 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 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 UserProfile objects correpsonding to users who match the search criteria
      Throws:
      UnsupportedOperatorException - if userSearch_ contains an invalid operator
      ServiceException - if any system-level error occurs

    • createUser

      String createUser(UserProfile userprofile_) throws DuplicateNameException, PrivilegeException, InvalidSupervisorException, InvalidUserException, InvalidNameException
      Creates a new user

      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:
      userprofile_ - a user to create
      Returns:
      the username of the user
      Throws:
      DuplicateNameException - if the username already exists
      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
      ServiceException - if any system-level error occurs
      InvalidNameException - Never thrown. Is only declared for backwards compatibility.

    • createUsers

      String[] createUsers(UserProfile[] userprofiles_) throws DuplicateNameException, InvalidNameException, PrivilegeException, InvalidSupervisorException, 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:
      userprofiles_ - 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 one of users_ is empty
      ServiceException - if any system-level error occurs

    • updateUser

      void updateUser(UserProfile userprofile_) throws InvalidUserException, InvalidSupervisorException, PrivilegeException
      Updates a user. Does not modify username or passwordfields.

      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:
      userprofile_ - the user to modify
      Throws:
      InvalidUserException - if a user with the 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

    • updateUsers

      void updateUsers(UserProfile[] userprofiles_) throws InvalidUserException, InvalidSupervisorException, PrivilegeException
      Updates users. Does not modify username or passwordfields. 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:
      userprofiles_ - 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:

    • findAllUsersPaging

      ResultPage findAllUsersPaging(boolean caseSensitive_, int startIndex_, int batchSize_, Integer sortProperty_, Integer sortOrder_)
      Fast method that gets all users. The ResultPage returned contains UserProfile objects sorted by the given sortProperty.
      Parameters:
      caseSensitive_ - whether the results should be sorted in a case sensitive manner. Pass false to sort in the common lexicographical order (e.g., a, A, b, B, c, C).
      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 UserProfile objects
      Throws:
      ServiceException - if any system-level error occurs

    • searchUserProfilesPaging

      ResultPage searchUserProfilesPaging(String query_, int startIndex_, int batchSize_, Integer sortProperty_, Integer sortOrder_)
      Searches for Users by first, last, and username and returns the UserProfile objects for each found User
      Parameters:
      query_ - The query by which to search for UserProfiles.
      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 UserProfile
      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 UserProfile objects which match the query.
      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

    • getUserPreferences

      UserPreferences getUserPreferences()
      Returns current user's preferences
      Returns:
      the UserPreferences

    • setUserPreferences

      void setUserPreferences(UserPreferences preferences_)
      Set current user's preferences
      Parameters:
      preferences_ - The UserPreferences for the current user