Package com.spotfire.ws.pub

Interface UserDirectoryService

public interface UserDirectoryService
A public SOAP web service for the TIBCO Spotfire Server User Directory.

Authorization

  • All access to this service require an access token that is issued for the "api.soap.user-directory-service" scope.
  • Modifying operations also require the calling user (the OAuth 2.0 client principal) to be a member of the Administrator group.

Important things to note

  • All modifying operations are atomic unless stated otherwise.
  • The domain name may be omitted where applicable, in which case the internal SPOTFIRE domain will be used instead.
Since:
5.5

  • Field Details

    • SERVICE_SCOPE

      static final String SERVICE_SCOPE
      The OAuth 2.0 scope needed to access any operation in this service.
      Since:
      7.13
      See Also:

  • Method Details

    • getUserByName

      UserPrincipal getUserByName(UserName userName) throws UserDirectoryServiceException
      Returns the user principal with the given name (consisting of both a name component and a domain).
      Parameters:
      userName - the name of the user, must not be null
      Returns:
      the requested user, or null if no such user exists
      Throws:
      UserDirectoryServiceException - if the user name is null or if an unexpected error occurs

    • getGroupByName

      GroupPrincipal getGroupByName(GroupName groupName) throws UserDirectoryServiceException
      Returns the group principal with the given name (consisting of both a name component and a domain).
      Parameters:
      groupName - the name of the group, must not be null
      Returns:
      the requested group, or null if no such group exists
      Throws:
      UserDirectoryServiceException - if the group name is null or if an unexpected error occurs

    • getUserById

      UserPrincipal getUserById(Guid id) throws UserDirectoryServiceException
      Returns the user with the given ID.
      Parameters:
      id - the ID of the user, must not be null
      Returns:
      the requested user, or null if no such user exists
      Throws:
      UserDirectoryServiceException - if the ID is null or if an unexpected error occurs

    • getGroupById

      GroupPrincipal getGroupById(Guid id) throws UserDirectoryServiceException
      Returns a GroupPrincipal object representing the group with the given ID.
      Parameters:
      id - the ID of the group, must not be null
      Returns:
      the requested group, or null if no such group exists
      Throws:
      UserDirectoryServiceException - if the ID is null or if an unexpected error occurs

    • searchUsers

      List<UserPrincipal> searchUsers(String searchExpression, int maxResults) throws UserDirectoryServiceException
      Returns all users, up to the specified upper limit, with names that matches the given search expression.

      The search expression should be a user name, or part thereof, with optional '?' (matches any single character) and '*' (matches zero or more characters) wildcards.

      Parameters:
      searchExpression - the search expression to match with the users' names, must not be null or empty
      maxResults - the maximum number of users to return, or a non-positive value if no limit should be imposed
      Returns:
      all users with names that matches the given search expression, in no particular order
      Throws:
      UserDirectoryServiceException - if the search expression is null or empty or if an unexpected error occurs

    • searchGroups

      List<GroupPrincipal> searchGroups(String searchExpression, int maxResults) throws UserDirectoryServiceException
      Returns all groups, up to the specified upper limit, with names that matches the given search expression.

      The search expression should be a group name, or part thereof, with optional '?' (matches any single character) and '*' (matches zero or more characters) wildcards.

      Parameters:
      searchExpression - the search expression to match with the groups' names
      maxResults - the maximum number of groups to return, or a non-positive value if no limit should be imposed
      Returns:
      all groups with names that matches the given search expression, in no particular order
      Throws:
      UserDirectoryServiceException - if the search expression is null or empty or if an unexpected error occurs

    • getMembers

      List<SpotfirePrincipal> getMembers(GroupName groupName) throws UserDirectoryServiceException
      Returns the immediate members of the given group.
      Parameters:
      groupName - the name of the group, must not be null
      Returns:
      all immediate members of the group, in no particular order
      Throws:
      UserDirectoryServiceException - if no group with the given name exists or if an unexpected error occurs

    • getImmediateGroups

      List<GroupPrincipal> getImmediateGroups(PrincipalName principalName) throws UserDirectoryServiceException
      Returns the immediate groups that the given principal (user or group) is a member of.
      Parameters:
      principalName - the name of the principal, must not be null
      Returns:
      all immediate groups that the given principal is a member of, in no particular order
      Throws:
      UserDirectoryServiceException - if no principal with the given type and name exists or if an unexpected error occurs

    • getAllGroups

      List<GroupPrincipal> getAllGroups(PrincipalName principalName) throws UserDirectoryServiceException
      Returns the groups (immediate or inherited) that the given principal (user or group) is a member of.
      Parameters:
      principalName - the name of the principal, must not be null
      Returns:
      all groups (immediate or inherited) that the given principal is a member of, in no particular order
      Throws:
      UserDirectoryServiceException - if no principal with the given type and name exists or if an unexpected error occurs

    • createUser

      UserPrincipal createUser(String username, String domainName, String displayName, String email, String password) throws UserDirectoryServiceException
      Creates a new user. If the password is null the user will not be able to login when using Spotfire Database as authentication method.

      Authorization
      The calling user must be a member of the Administrator group.

      Parameters:
      username - the name of the user, must not be null or an empty string and must not exceed 50 characters
      domainName - the domain name, must not be null or an empty string and must not exceed 50 characters
      displayName - the display name, must not be null or an empty string and must not exceed 100 characters
      email - the e-mail address, may be null but must not be an empty string or an invalid e-mail address
      password - the new password, may be null but must not be an empty string
      Returns:
      the newly created user
      Throws:
      UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the user name, the display name, the e-mail address or the password is invalid, if a user with the same name already exists in the same domain or if an unexpected error occurs

    • createGroup

      GroupPrincipal createGroup(String groupname, String displayName, String email) throws UserDirectoryServiceException
      Creates a new group. Note that groups can only be created in the internal SPOTFIRE domain using this method. Groups may belong to other domains but only when created through LDAP group synchronization.

      Authorization
      The calling user must be a member of the Administrator group.

      Parameters:
      groupname - the name of the group, must not be null or an empty string and must not exceed 50 characters
      displayName - the display name, must not be null or an empty string and must not exceed 100 characters
      email - the e-mail address, may be null but must not be an empty string or an invalid e-mail address
      Returns:
      the newly created group
      Throws:
      UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the group name, the display name or the e-mail address is invalid, if a group with the same name already exists in the same domain or if an unexpected error occurs

    • removePrincipals

      void removePrincipals(List<PrincipalName> principalNames) throws UserDirectoryServiceException
      Removes the given principals (users and groups).

      Authorization
      The calling user must be a member of the Administrator group.

      Parameters:
      principalNames - the names of the principals to remove, may be empty in which case no changes will be made
      Throws:
      UserDirectoryServiceException - if the calling user doesn't have sufficient privileges or if an unexpected error occurs

    • setName

      void setName(PrincipalName principalName, String name) throws UserDirectoryServiceException
      Sets the name for the given principal (user or group).

      Authorization
      The calling user must be a member of the Administrator group.

      Parameters:
      principalName - the name of the principal to set the name for, must not be null
      name - the new name, must not be null or an empty string and must not exceed 50 characters
      Throws:
      UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the principal doesn't exist, if the name is invalid, if another principal of the same type with the new name already exists in the same domain or if an unexpected error occurs

    • setDisplayName

      void setDisplayName(PrincipalName principalName, String displayName) throws UserDirectoryServiceException
      Sets the display name for the given principal (user or group).

      Authorization
      The calling user must be a member of the Administrator group.

      Parameters:
      principalName - the name of the principal to set the display name for, must not be null
      displayName - the new display name, must not be null or an empty string and must not exceed 100 characters
      Throws:
      UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the principal doesn't exist, if the display name is invalid or if an unexpected error occurs

    • setEmail

      void setEmail(PrincipalName principalName, String email) throws UserDirectoryServiceException
      Sets the e-mail address for the given principal (user or group).

      Authorization
      The calling user must be a member of the Administrator group.

      Parameters:
      principalName - the name of the principal to set the e-mail address for, must not be null
      email - the new e-mail address, may be null but must not be an empty string or an invalid e-mail address
      Throws:
      UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the principal doesn't exist, if the e-mail address is invalid or if an unexpected error occurs

    • setPassword

      void setPassword(UserName userName, String password) throws UserDirectoryServiceException
      Sets the password for the given user. If the password is null any existing password will be cleared and the user will not be able to login when using Spotfire Database as authentication method.

      Authorization
      The calling user must be a member of the Administrator group.

      Parameters:
      userName - the name of the user to set the password for, must not be null
      password - the new password, may be null but must not be an empty string
      Throws:
      UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the user doesn't exist, if the password is invalid or if an unexpected error occurs

    • setUserEnabled

      void setUserEnabled(UserName userName, boolean enabled) throws UserDirectoryServiceException
      Enables or disables the given user.

      Authorization
      The calling user must be a member of the Administrator group.

      Parameters:
      userName - the name of the user to set the enabled flag for, must not be null
      enabled - the new value for the enabled flag
      Throws:
      UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the user doesn't exist or if an unexpected error occurs

    • isMember

      boolean isMember(GroupName groupName, PrincipalName principalName) throws UserDirectoryServiceException
      Returns true if the given principal (user or group) is a member (immediate or otherwise) of the given group.
      Parameters:
      groupName - the name of the group to determine membership of, must not be null
      principalName - the name of the principal to determine membership for, must not be null
      Returns:
      true if the given principal is a member of the given group and false otherwise
      Throws:
      UserDirectoryServiceException - if the group or the principal doesn't exist or if an unexpected error occurs

    • addMembers

      void addMembers(GroupName groupName, List<PrincipalName> memberNames) throws UserDirectoryServiceException
      Adds the given principals (users or groups) to the given group.

      Authorization
      The calling user must be a member of the Administrator group.

      Parameters:
      groupName - the name of the group which the principals should be added to
      memberNames - the names of the principals that should be added to the group
      Throws:
      UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the group principal or any of the member principals doesn't exist or if an unexpected error occurs

    • removeMembers

      void removeMembers(GroupName groupName, List<PrincipalName> memberNames) throws UserDirectoryServiceException
      Removes the given principals (users or groups) from the given group.

      Authorization
      The calling user must be a member of the Administrator group.

      Parameters:
      groupName - the name of the group which the principals should be removed from
      memberNames - the names of the principals that should be removed from the group
      Throws:
      UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the group principal doesn't exists or if an unexpected error occurs

    • setMembers

      void setMembers(GroupName groupName, List<PrincipalName> memberNames) throws UserDirectoryServiceException
      Sets the given principals (users or groups) as members of the given group. Any existing members will be removed.

      Authorization
      The calling user must be a member of the Administrator group.

      Parameters:
      groupName - the name of the group for which the the members should be set
      memberNames - the names of the principals that should be set as members of the group
      Throws:
      UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the group principal or any of the member principals doesn't exist or if an unexpected error occurs