Account - manage accounts


Shane P. McCarron <>


Copyright 2001-2011 Applied Testing and Technology, Inc. All Rights Reserved.


use Account;

# open up the account database for writing
my $acct = new Account(1);

# set user information
$acct->userInfo($username, { userData } );

# save the user information

# get the list of users
@list = $acct->userList();

The Account object allows creation, updating, and management of user accounts. See the UserInfo object for tools to authenticate users and manage access control.



a handle to the lock that is set for the object


a boolean that indicates whether the session is open read/write


a boolean to indicate if the file is from a DBM source


a hash of information about each user defined in the suite {userName}->{email, fullname, phoneNumber, password, logintime, accesstime, totalTime, disabled, forceChange}


a hash access control list for the features and test suites {acl}->{account, execute, browse, edit, manage}. Also sub-hashes for test suites in {acl}->{suiteName}


a hash containing report preferences, including a sub-hash containing report customizations on a per test suite/per report basis

{report}->{pref1, pref2},
{report}->{custom}->{suiteName}->{pref1, pref2}


new - open up the account file

$acct = new Account(read/write [, timeout]);

Creates a new account object.

read/write - boolean set to True if the existing session needs to be writeable. Defaults to readOnly.

timeout - the number of seconds to wait for a lock. Defaults to 60 seconds.

returns a reference to the Account object.

path - get the path to the account database

returns a path to the account database file

print - print the contents of the account list


returns the string-ified version of the entire session, or just the contents of test testNum, if specified.

hasExpired - accessor to see if the license has expired

$exp = $acct->hasExpired;

Returns 1 if the license has been recorded as expired, and 0 if it has not.

maxLoggedInWhen - tell when the high water mark was hit

Returns the time when the high water mark in terms of logged in users was hit, or the current time if no high water mark is defined.

maxLoggedIn - tell how many users at the high water mark

Returns the maximum number of users ever logged in, or 0 if no high water mark is defined.

sessClear - clear an individual session custom setting

$setting = $acct->sessClear(user, sid, name ) ;

clears out the setting from the session data structure.

Returns nothing.

sessSet - set/get an individual session custom setting

$setting = $acct->sessSet(user, sid, name [, value] );

returns the individual setting, or undef if it is not defined. If a value is provided, it updates the setting data structure with the new setting for "name".

setting - set/get an individual custom setting

$setting = $acct->setting(user, name [, value] );

returns the individual setting, or undef if it is not defined. If a value is provided, it updates the setting data structure with the new setting for "name".

fullname - return the fullname for a username

$fullname = $acct->fullname(userId [, includeUID]) ;

userId - an id of a user in the database

includeUID - a boolean. If true then include the userID after the fullname in parens. Defaults to false.

Returns the fullname for the user, or the userId if there is no fullname.

clear - delete a setting from a user

$setRef = $acct->clear(user, setting) ;

Removes the setting from the user, if the user has one at all.

Returns nothing.

lastChange - get/set the last major change time

$last = $acct->lastChange ( [time() ] );

A major change is defined as one that changes the list of users and/or the list of users that have access to specific test suites.

Returns the last time. If the optional parameter is supplied, sets the last change time to then.

settings - set/get the user's custom settings

$setRef = $userInfo->settings( user [, settings ] );

returns a reference to the settings hash within the user's data structure, or replaces the settings hash with an updated version and marks the data structure as dirty.

sessionList - return a list of sessions

@list = $acct->sessionList( [ sortDir [, $uname ] ] );

returns a list of all sessions, or sessions for only a specific user.

each list item is a reference to a hash containing:

release - release the database

$acct->release() ;

remove - remove a user from the database


Returns 1 on success. Returns 0 if there was no such user or if there is no write access to the database.

Note that this will rebuild the userHash, including the per-suite user hash for any suites to which this user had access.

numUsers - accessor for the number of users


returns the number of users in the database.

save - save the Account DB

Flushes the database to disk

buildUserHash - force a rebuild of the hash

$acct->buildUserHash( [ $suiteListRef ] ) ;

suiteListRef is a reference to a list of test suite names that also need updating. If not defined, then all suites are updated. If the list is empty, then no suites are updated.

Rebuilds the internal userhash structure. Returns nothing.

renameSuite - handle a suite rename

$acct->renameSuite(oldname, newname);

Will traverse the database and update settings to reference the new suite name.

userHash - return a hash of users by shortname

%hash = $acct->userHash();

returns a hash whose keys are the short names, and values are the fullnames of each user. The list is based upon an internal cache that is maintained by the object itself.

userList - return a complete list of users


returns a sorted array of the names of the defined users.

userList( [ Suite [, perm] ] )

Returns a sorted array that includes only the users with access to suite Suite. If Suite is not specified, then just returns all the users defined in the system.

userInfo - accessor for user account attributes

$acct->userInfo(username, dataHash);

username is the user account data

dataHash is a hash of fields for the user. If you "undef" a field, then its contents will be removed.

Defined attributes for a user include:


the full name of the user.


the email address of the user.


the comma-separated list of "groups" in which this user is a member.


the phone number of the user.


the password for the user.


the time the user logged in.


the time the user last accessed the system.


The total time this user has been logged into the system.


Boolean that indicates if this account is currently disabled.


Force the change of the user's password on the next login.

returns the handle to the userInfo hash.

findUser - return the real username for a user

$username = $acct->findUser($username) ;

Returns the original user name or, if caseInsensitive is enabled, the username that matches.

userPerms - return a hash mapping userid to permission levels for a suite

$hRef = $acct->userPerms( suite ) ;

Suite is the name of a test suite.

Returns a reference to a hash mapping userids to the permission number for each user who has any access to the suite at all.

zonePicker - present menus for picking a timezone

$output = $acct->zonePicker(formName, varname, current);

formName is the name for this form on the page.

varname is the name of the HTML form variable to use.

current is the current setting.

Returns the HTML to generate the timezone picker selection elements.

suite - accessor for a suitename

$acct->suite( suiteName) ;

suiteName is the name of a suite. The account object will remember that you are working in the context of that suite for purposes of evaluation user permissions.

SQL_updateAccountList - update the list of accounts and perms

$acct->SQL_updateAccountList( suite [, ulistRef ] ) ;

suite is the name of the suite to update.

ulistRef is a reference to a list of users who have access to this suite.

Updates the master user table with all userids and associated data. Updates the authentication table with information about the auth level for each user with access to the suite.

In the situation where multiple suites share the same database space/ table space, this is wildly inefficient. But it doesn't happen all that often, so...

Returns nothing.

SQL_tname - return the table name

my $tname = $sdb->SQL_tname;

Returns the name of the table for this object.

SQL_tlist - return the list of tables

@tlist = $sdb->SQL_tlist;

SQL_tableDef - return an array of table row definitions

@rows = $acc->SQL_tableDef( table )

table is the name of the table to generate.

Returns a list of rows for the table.

SQL_createTables - create the user data table(s)

$account->SQL_createTables( );

Returns nothing.

Copyright © 2000-2013 Applied Testing and Technology, Inc. All rights reserved.