NAME

BuildForge::Services::DBO::User


SYNOPSIS

        use BuildForge::Services;
        $conn = new BuildForge::Services::Connection($hostname);
        $token = $conn->authUser($user, $pass);
        
        # Getting existing users
        $allUsers = BuildForge::Services::DBO::User->findAll($conn);
        $olduser = BuildForge::Services::DBO::User->findById($conn, $userId);
        $olduser2 = BuildForge::Services::DBO::User->findByLogin($conn, 'login');
        # Getter / setter functions
        $id = $olduser->getUserId();
        $username = $olduser->getName();
        $login = $olduser->getLogin();
        $email = $olduser->getEmail();
        $maximumDailyBuilds = $olduser->getMaxBuilds();
        $timezone = $olduser->getTimeZone();
        $dateFormat = $olduser->getDateFormat();
        $locale = $olduser->getLocale();
        $wasPasswordUpdated = $olduser->getPasswordUpdated();
        $doesPasswordExpire = $olduser->getPasswordExpires();
        $hasPasswordExpired = $olduser->getPasswordExpired();
        $isPriorityUser = $olduser->getPriority();
        $isLDAPUser = $olduser->getLdap();
        
        $olduser->setName('New User Name');
        $olduser->setLogin('newlogin');
        $olduser->setPassword('password');
        $olduser->setEmail('login@company.com');
        $olduser->setMaxBuilds(5);
        $olduser->setTimeZone('PDT');
        $olduser->setDateFormat('%D %I:%M%p');
        $olduser->setLocale('en_US');
        $olduser->setPasswordExpires(1);
        $olduser->setPasswordExpired(0);
        $olduser->setPriority(1);
        $olduser->update();
        
        # User creation, updating, access group control, deletion
        $newuser = new BuildForge::Services::DBO::User($conn);
        $newuser->setName('Newly Created User');
        $newuser->setLogin('newerlogin');
        $newuser->setPassword('password');
        $newuser->create();
        $newuser->setEmail('newerlogin@company.com');
        $newuser->update();
        
        $newuser->resetLicense();
        $newuser->resetLogin();
        
        $accessGroup = BuildForge::Services::DBO::AccessGroup->findByName($conn, 'MyAccessGroup');
        $newuser->addAccessGroup($accessGroup->getLevel());
        $newuser->deleteAccessGroup($accessGroup->getLevel());
        
        $newuser->delete();
        BuildForge::Services::DBO::User->deleteById($conn, $olduser->getUserId());
                
        $conn->logout;
        $conn->close;


DESCRIPTION

User allows you to create, access, and delete BuildForge users.


METHODS

new BuildForge::Services::DBO::User(connection, {UserParamsHashRef})

Returns a new instance of a User object.

connection

A connected BuildForge::Services::Connection object.

UserParamsHashRef

An optional reference to a hash containing any or all of the following fields.

name

The displayed name of the user.

login

The user's login name.

password

The user's login password. This must match the engine's password security settings. See the ``Password Format'' system configuration setting and the related online help information for details.

email

The user's email address where notification emails should be sent.

maxBuilds

The user's maximum number of daily builds. A value of 0 (the default) allows the user to start unlimited builds.

passwordExpires

If this evaluates to true (the default), the user's password expires after a number of days set in the ``Password Expiration Days'' system configuration setting. If this evaluates to false, the user's password doesn't expire.

timeZone

The user's timezone (from $timezone->getZoneId()).

dateFormat

The date format for date strings that appear in the user interface for the user. This uses the POSIX strftime() function - check your local system implementation of this to see what values it accepts.

priority

The user is a priority user if this evaluates to true and isn't if this evaluates to false. When a priority user logs in, if there are too many users currently connected to the BuildForge console due to license restrictions, one of those users gets bumped off to make way for the priority user to log in.

locale

The user's locale, such as 'en_US' (the default), which controls the user's language settings.

BuildForge::Services::DBO::User->findAll(connection)

Returns a reference to an array of BuildForge::Services::DBO::User objects corresponding to all users in the database.

connection

A connected BuildForge::Services::Connection object.

BuildForge::Services::DBO::User->findById(connection, userId)

Returns the BuildForge::Services::DBO::User object corresponding to the given user ID, or undef if no such object exists.

connection

A connected BuildForge::Services::Connection object.

userId

The user ID (from $user->getUserId()) for the desired user.

BuildForge::Services::DBO::User->findByLogin(connection, login)

Returns the BuildForge::Services::DBO::User object corresponding to the given user login, or undef if no such object exists.

connection

A connected BuildForge::Services::Connection object.

userId

The user login (from $user->getLogin()) for the desired user.

$user->create()

Creates the user record within the database.

$user->update()

Updates the user record within the database.

$user->resetLicense()

Resets the user's license information, causing them to no longer take up a license seat until they log back in. Note that this does not log the user out of the services layer - the user's session within the services layer is valid until the user logs out.

$user->resetLogin()

Logs the user out of the BuildForge system. This does not log the user out of the services layer, just out of the web-based UI.

$user->addAccessGroup(accessGroupId)

Adds the user to an access group. Access group membership controls both user permissions and what objects the user has access to within the system. The root user cannot get added to any access groups.

accessGroupId

The access group ID (from $accessGroup->getLevel()) of the access group.

$user->deleteAccessGroup(accessGroupId)

Removes the user from an access group. Access group membership controls both user permissions and what objects the user has access to within the system.

accessGroupId

The access group ID (from $accessGroup->getLevel()) of the access group.

$user->delete()

Deletes the user record from the database. The root user cannot get deleted.

BuildForge::Services::DBO::User->deleteById(connection, userId)

Deletes the user record with the given ID from the database. The root user (ID of 1) cannot get deleted.

connection

A connected BuildForge::Services::Connection object.

userId

The user ID (from $user->getUserId()) to delete.

$user->getUserId()

Returns the user's ID.

$user->getName()

Returns the user's name.

$user->getLogin()

Returns the user's login name.

$user->getEmail()

Returns the user's email address.

$user->getMaxBuilds()

Returns the user's maximum daily builds or 0 if the user has unlimited builds.

$user->getTimeZone()

Returns the user's timezone.

$user->getDateFormat()

Returns the date format for date strings that appear in the user interface for the user. This uses the POSIX strftime() function - check your local system implementation of this to see what values it accepts.

$user->getLocale()

Returns the user's language settings.

$user->getPasswordUpdated()

Returns the timestamp for the last time the user was updated. This is only logged if the system expires passwords with the ``Password Expiration Days'' system configuration setting.

$user->getPasswordExpires()

Returns 1 if the user's password expires and 0 if it doesn't.

$user->getPasswordExpired()

Returns 1 if the user's password has expired and 0 if it hasn't.

$user->getPriority()

Returns 1 if the user is a priority user and 0 if it isn't. When a priority user logs in, if there are too many users currently connected to the BuildForge console due to license restrictions, one of those users gets bumped off to make way for the priority user to log in.

$user->getLdap()

Returns 1 if the user is an LDAP user and 0 if they aren't.

$user->setName(userName)

Sets the user's name. $user->update() must be run before changes are replicated in the database.

userName

The new user name string.

$user->setLogin(login)

Sets the user's login. $user->update() must be run before changes are replicated in the database.

login

The new login name string.

$user->setPassword(password)

Sets the user's password. This must match the engine's password security settings. See the ``Password Format'' system configuration setting and the related online help information for details. $user->update() must be run before changes are replicated in the database.

password

The new password string.

$user->setEmail(email)

Sets the user's email address which notification emails get sent to. $user->update() must be run before changes are replicated in the database.

email

The new email address string.

$user->setMaxBuilds(maxBuilds)

Sets the users maximum daily builds. $user->update() must be run before changes are replicated in the database.

maxBuilds

The new number of daily builds, or 0 to allow unlimited builds.

$user->setTimeZone(timeZoneId)

Sets the user's timezone. $user->update() must be run before changes are replicated in the database.

timeZoneId

The timezone ID (from $timezone->getZoneId()) for the new user timezone.

$user->setDateFormat(dateFormat)

Sets the date format for date strings that appear in the user interface for the user. $user->update() must be run before changes are replicated in the database.

dateFormat

The new date format. This uses the POSIX strftime() function - check your local system implementation of this to see what values it accepts.

$user->setLocale(locale)

Sets the user's locale, which controls the user's language settings. $user->update() must be run before changes are replicated in the database.

locale

The new locale, such as 'en_US'.

$user->setPasswordExpires(doesPasswordExpire)

Sets whether the user's password expires on a schedule controlled by the ``Password Expiration Days'' system configuration setting. $user->update() must be run before changes are replicated in the database.

doesPasswordExpire

If this evaluates to true, the password does expire, and if not, it doesn't.

$user->setPasswordExpired(hasPasswordExpired)

Sets whether the user's password has expired. $user->update() must be run before changes are replicated in the database.

hasPasswordExpired

If this evaluates to true, the password has expired, and the user must change their password when next they log in. If this evaluates to false, the password hasn't expired.

$user->setPriority(isPriorityUser)

Sets whether or not the user is a priority user. When a priority user logs in, if there are too many users currently connected to the BuildForge console due to license restrictions, one of those users gets bumped off to make way for the priority user to log in. $user->update() must be run before changes are replicated in the database.

isPriorityUser

The user becomes a priority user if this evaluates to true and doesn't if this evaluates to false.


COPYRIGHT

Copyright (c)2006-2007 International Business Machines, Inc. All rights reserved.