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

    • getUser$UPDATES

      @Deprecated(forRemoval=true) static final boolean getUser$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • getUsers$UPDATES

      @Deprecated(forRemoval=true) static final boolean getUsers$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • getUserByUuid$UPDATES

      @Deprecated(forRemoval=true) static final boolean getUserByUuid$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • getUsersByUuid$UPDATES

      @Deprecated(forRemoval=true) static final boolean getUsersByUuid$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • getUsersCreation$UPDATES

      @Deprecated(forRemoval=true) static final boolean getUsersCreation$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • getUsersForGroupByRolePaging$UPDATES

      @Deprecated(forRemoval=true) static final boolean getUsersForGroupByRolePaging$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • authenticateUser$UPDATES

      @Deprecated(forRemoval=true) static final boolean authenticateUser$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • findUsers$UPDATES

      @Deprecated(forRemoval=true) static final boolean findUsers$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • findUsersPaging$UPDATES

      @Deprecated(forRemoval=true) static final boolean findUsersPaging$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • createUser$UPDATES

      @Deprecated(forRemoval=true) static final boolean createUser$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • createUsers$UPDATES

      @Deprecated(forRemoval=true) static final boolean createUsers$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • updateUser$UPDATES

      @Deprecated(forRemoval=true) static final boolean updateUser$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • updateUsers$UPDATES

      @Deprecated(forRemoval=true) static final boolean updateUsers$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • findAllUsersPaging$UPDATES

      @Deprecated(forRemoval=true) static final boolean findAllUsersPaging$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • searchUserProfilesPaging$UPDATES

      @Deprecated(forRemoval=true) static final boolean searchUserProfilesPaging$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • getApplicationName$UPDATES

      @Deprecated(forRemoval=true) static final boolean getApplicationName$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • getWorkspace$UPDATES

      @Deprecated(forRemoval=true) static final boolean getWorkspace$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • getUserPreferences$UPDATES

      @Deprecated(forRemoval=true) static final boolean getUserPreferences$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • setUserPreferences$UPDATES

      @Deprecated(forRemoval=true) static final boolean setUserPreferences$UPDATES
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

  • Method Details

    • getUser

      @Read(K_PERSONALIZATION) 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

    • getUsers

      @Read(K_PERSONALIZATION) 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

    • getUserByUuid

      @Read(K_PERSONALIZATION) 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

    • getUsersByUuid

      @Read(K_PERSONALIZATION) 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

    • getUsersCreation

      @Read(K_PERSONALIZATION) 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 @Read(K_PERSONALIZATION) 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

    • authenticateUser

      @Deprecated @Read(K_PERSONALIZATION) 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

    • findUsers

      @Deprecated @Read(K_PERSONALIZATION) 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

    • findUsersPaging

      @Read(K_PERSONALIZATION) 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

    • createUser

      @Write(K_PERSONALIZATION) 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
      InvalidNameException - Never thrown. Is only declared for backwards compatibility.

    • createUsers

      @Write(K_PERSONALIZATION) 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

    • updateUser

      @Write(K_PERSONALIZATION) 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
      PrivilegeException

    • updateUsers

      @Write(K_PERSONALIZATION) 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
      PrivilegeException
      See Also:

    • findAllUsersPaging

      @Read(K_PERSONALIZATION) 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

    • searchUserProfilesPaging

      @Read(K_PERSONALIZATION) 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.

    • getApplicationName

      @Read(K_PERSONALIZATION) String getApplicationName()
      Gets the name of the application on which this service is running.
      Returns:
      the name of the application

    • getWorkspace

      @Read(K_PERSONALIZATION) 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.

    • getUserPreferences

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

    • setUserPreferences

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