1 package FS::access_user;
2 use base qw( FS::m2m_Common FS::option_Common );
5 use vars qw( $DEBUG $me );
9 use FS::Record qw( qsearch qsearchs dbh );
15 $me = '[FS::access_user]';
19 FS::access_user - Object methods for access_user records
25 $record = new FS::access_user \%hash;
26 $record = new FS::access_user { 'column' => 'value' };
28 $error = $record->insert;
30 $error = $new_record->replace($old_record);
32 $error = $record->delete;
34 $error = $record->check;
38 An FS::access_user object represents an internal access user. FS::access_user
39 inherits from FS::Record. The following fields are currently supported:
51 =item _password_encoding
65 Master customer for this employee (for commissions)
69 Default sales person for this employee (for reports)
83 Creates a new internal access user. To add the user to the database, see L<"insert">.
85 Note that this stores the hash reference, not a distinct copy of the hash it
86 points to. You can ask the object for a copy with the I<hash> method.
90 # the new method can be inherited from FS::Record, if a table method is defined
92 sub table { 'access_user'; }
94 sub _option_table { 'access_user_pref'; }
95 sub _option_namecol { 'prefname'; }
96 sub _option_valuecol { 'prefvalue'; }
100 Adds this record to the database. If there is an error, returns the error,
101 otherwise returns false.
108 my $error = $self->check;
109 return $error if $error;
111 local $SIG{HUP} = 'IGNORE';
112 local $SIG{INT} = 'IGNORE';
113 local $SIG{QUIT} = 'IGNORE';
114 local $SIG{TERM} = 'IGNORE';
115 local $SIG{TSTP} = 'IGNORE';
116 local $SIG{PIPE} = 'IGNORE';
118 my $oldAutoCommit = $FS::UID::AutoCommit;
119 local $FS::UID::AutoCommit = 0;
123 $dbh->rollback or die $dbh->errstr if $oldAutoCommit;
127 $error = $self->SUPER::insert(@_);
130 $dbh->rollback or die $dbh->errstr if $oldAutoCommit;
133 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
141 Delete this record from the database.
148 local $SIG{HUP} = 'IGNORE';
149 local $SIG{INT} = 'IGNORE';
150 local $SIG{QUIT} = 'IGNORE';
151 local $SIG{TERM} = 'IGNORE';
152 local $SIG{TSTP} = 'IGNORE';
153 local $SIG{PIPE} = 'IGNORE';
155 my $oldAutoCommit = $FS::UID::AutoCommit;
156 local $FS::UID::AutoCommit = 0;
159 my $error = $self->SUPER::delete(@_);
162 $dbh->rollback or die $dbh->errstr if $oldAutoCommit;
165 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
171 =item replace OLD_RECORD
173 Replaces the OLD_RECORD with this one in the database. If there is an error,
174 returns the error, otherwise returns false.
181 my $old = ( ref($_[0]) eq ref($new) )
185 local $SIG{HUP} = 'IGNORE';
186 local $SIG{INT} = 'IGNORE';
187 local $SIG{QUIT} = 'IGNORE';
188 local $SIG{TERM} = 'IGNORE';
189 local $SIG{TSTP} = 'IGNORE';
190 local $SIG{PIPE} = 'IGNORE';
192 my $oldAutoCommit = $FS::UID::AutoCommit;
193 local $FS::UID::AutoCommit = 0;
196 return "Must change password when enabling this account"
197 if $old->disabled && !$new->disabled
198 && ( $new->_password =~ /changeme/i
199 || $new->_password eq 'notyet'
202 my $error = $new->SUPER::replace($old, @_);
205 $dbh->rollback or die $dbh->errstr if $oldAutoCommit;
208 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
216 Checks all fields to make sure this is a valid internal access user. If there is
217 an error, returns the error, otherwise returns false. Called by the insert
222 # the check method should currently be supplied - FS::Record contains some
223 # data checking routines
229 $self->ut_numbern('usernum')
230 || $self->ut_alpha_lower('username')
231 || $self->ut_textn('_password')
232 || $self->ut_textn('last')
233 || $self->ut_textn('first')
234 || $self->ut_foreign_keyn('user_custnum', 'cust_main', 'custnum')
235 || $self->ut_foreign_keyn('report_salesnum', 'sales', 'salesnum')
236 || $self->ut_enum('disabled', [ '', 'Y' ] )
238 return $error if $error;
245 Returns a name string for this user: "Last, First".
251 return $self->username
252 if $self->get('last') eq 'Lastname' && $self->first eq 'Firstname'
253 or $self->get('last') eq '' && $self->first eq '';
254 return $self->get('last'). ', '. $self->first;
259 Returns the FS::cust_main object (see L<FS::cust_main>), if any, for this
266 qsearchs( 'cust_main', { 'custnum' => $self->user_custnum } );
271 Returns the FS::sales object (see L<FS::sales>), if any, for this
278 qsearchs( 'sales', { 'salesnum' => $self->report_salesnum } );
281 =item access_usergroup
283 Returns links to the the groups this user is a part of, as FS::access_usergroup
284 objects (see L<FS::access_usergroup>).
288 Returns a list of agentnums this user can view (via group membership).
294 my $sth = dbh->prepare(
295 "SELECT DISTINCT agentnum FROM access_usergroup
296 JOIN access_groupagent USING ( groupnum )
298 ) or die dbh->errstr;
299 $sth->execute($self->usernum) or die $sth->errstr;
300 map { $_->[0] } @{ $sth->fetchall_arrayref };
305 Returns a hashref of agentnums this user can view.
311 scalar( { map { $_ => 1 } $self->agentnums } );
314 =item agentnums_sql [ HASHREF | OPTION => VALUE ... ]
316 Returns an sql fragement to select only agentnums this user can view.
318 Options are passed as a hashref or a list. Available options are:
324 The frament will also allow the selection of null agentnums.
328 The fragment will also allow the selection of null agentnums if the current
329 user has the provided access right
333 Optional table name in which agentnum is being checked. Sometimes required to
334 resolve 'column reference "agentnum" is ambiguous' errors.
338 All agents will be viewable if the current user has the provided access right.
339 Defaults to 'View customers of all agents'.
347 my %opt = ref($_[0]) ? %{$_[0]} : @_;
349 my $agentnum = $opt{'table'} ? $opt{'table'}.'.agentnum' : 'agentnum';
353 my $viewall_right = $opt{'viewall_right'} || 'View customers of all agents';
354 if ( $self->access_right($viewall_right) ) {
355 push @or, "$agentnum IS NOT NULL";
357 my @agentnums = $self->agentnums;
358 push @or, "$agentnum IN (". join(',', @agentnums). ')'
362 push @or, "$agentnum IS NULL"
364 || ( $opt{'null_right'} && $self->access_right($opt{'null_right'}) );
366 return ' 1 = 0 ' unless scalar(@or);
367 '( '. join( ' OR ', @or ). ' )';
373 Returns true if the user can view the specified agent.
375 Also accepts optional hashref cache, to avoid redundant database calls.
380 my( $self, $agentnum, $cache ) = @_;
382 return $cache->{$self->usernum}->{$agentnum}
383 if $cache->{$self->usernum}->{$agentnum};
384 my $sth = dbh->prepare(
385 "SELECT COUNT(*) FROM access_usergroup
386 JOIN access_groupagent USING ( groupnum )
387 WHERE usernum = ? AND agentnum = ?"
388 ) or die dbh->errstr;
389 $sth->execute($self->usernum, $agentnum) or die $sth->errstr;
390 $cache->{$self->usernum}->{$agentnum} = $sth->fetchrow_arrayref->[0];
392 return $cache->{$self->usernum}->{$agentnum};
395 =item agents [ HASHREF | OPTION => VALUE ... ]
397 Returns the list of agents this user can view (via group membership), as
398 FS::agent objects. Accepts the same options as the agentnums_sql method.
406 'hashref' => { disabled=>'' },
407 'extra_sql' => ' AND '. $self->agentnums_sql(@_),
408 'order_by' => 'ORDER BY agent',
412 =item access_users [ HASHREF | OPTION => VALUE ... ]
414 Returns an array of FS::access_user objects, one for each non-disabled
415 access_user in the system that shares an agent (via group membership) with
416 the invoking object. Regardless of options and agents, will always at
417 least return the invoking user and any users who have viewall_right.
419 Accepts the following options:
425 Only return users who appear in the usernum field of this table
429 Include disabled users if true (defaults to false)
433 All users will be returned if the current user has the provided
434 access right, regardless of agents (other filters still apply.)
435 Defaults to 'View customers of all agents'
439 #Leaving undocumented until such time as this functionality is actually used
443 #Users with no agents will be returned.
447 #Users with no agents will be returned if the current user has the provided
452 my %opt = ref($_[0]) ? %{$_[0]} : @_;
453 my $table = $opt{'table'};
454 my $search = { 'table' => 'access_user' };
455 $search->{'hashref'} = $opt{'disabled'} ? {} : { 'disabled' => '' };
456 $search->{'addl_from'} = "INNER JOIN $table ON (access_user.usernum = $table.usernum)"
458 my @access_users = qsearch($search);
459 my $viewall_right = $opt{'viewall_right'} || 'View customers of all agents';
460 return @access_users if $self->access_right($viewall_right);
461 #filter for users with agents $self can view
463 my $agentnum_cache = {};
465 foreach my $access_user (@access_users) {
466 # you can always view yourself, regardless of agents,
467 # and you can always view someone who can view you,
468 # since they might have affected your customers
469 if ( ($self->usernum eq $access_user->usernum)
470 || $access_user->access_right($viewall_right)
472 push(@out,$access_user);
475 # if user has no agents, you need null or null_right to view
476 my @agents = $access_user->agents('viewall_right'=>'NONE'); #handled viewall_right above
479 ( $opt{'null_right'} && $self->access_right($opt{'null_right'}) )
481 push(@out,$access_user);
485 # otherwise, you need an agent in common
486 foreach my $agent (@agents) {
487 if ($self->agentnum($agent->agentnum,$agentnum_cache)) {
488 push(@out,$access_user);
496 =item access_users_hashref [ HASHREF | OPTION => VALUE ... ]
498 Accepts same options as L</access_users>. Returns a hashref of
499 users, with keys of usernum and values of username.
503 sub access_users_hashref {
505 my %access_users = map { $_->usernum => $_->username }
506 $self->access_users(@_);
507 return \%access_users;
510 =item access_right RIGHTNAME | LISTREF
512 Given a right name or a list reference of right names, returns true if this
513 user has this right, or, for a list, one of the rights (currently via group
514 membership, eventually also via user overrides).
519 my( $self, $rightname ) = @_;
521 $rightname = [ $rightname ] unless ref($rightname);
523 warn "$me access_right called on ". join(', ', @$rightname). "\n"
526 #some caching of ACL requests for low-hanging fruit perf improvement
527 #since we get a new $CurrentUser object each page view there shouldn't be any
528 #issues with stickiness
529 if ( $self->{_ACLcache} ) {
531 unless ( grep !exists($self->{_ACLcache}{$_}), @$rightname ) {
532 warn "$me ACL cache hit for ". join(', ', @$rightname). "\n"
534 return scalar( grep $self->{_ACLcache}{$_}, @$rightname );
537 warn "$me ACL cache miss for ". join(', ', @$rightname). "\n"
542 warn "initializing ACL cache\n"
544 $self->{_ACLcache} = {};
548 my $has_right = ' rightname IN ('. join(',', map '?', @$rightname ). ') ';
550 my $sth = dbh->prepare("
551 SELECT groupnum FROM access_usergroup
552 LEFT JOIN access_group USING ( groupnum )
553 LEFT JOIN access_right
554 ON ( access_group.groupnum = access_right.rightobjnum )
556 AND righttype = 'FS::access_group'
559 ") or die dbh->errstr;
560 $sth->execute($self->usernum, @$rightname) or die $sth->errstr;
561 my $row = $sth->fetchrow_arrayref;
563 my $return = $row ? $row->[0] : '';
565 #just caching the single-rightname hits should be enough of a win for now
566 if ( scalar(@$rightname) == 1 ) {
567 $self->{_ACLcache}{${$rightname}[0]} = $return;
574 =item default_customer_view
576 Returns the default customer view for this user, from the
577 "default_customer_view" user preference, the "cust_main-default_view" config,
578 or the hardcoded default, "basics" (formerly "jumbo" prior to 3.0).
582 sub default_customer_view {
585 $self->option('default_customer_view')
586 || FS::Conf->new->config('cust_main-default_view')
587 || 'basics'; #s/jumbo/basics/ starting with 3.0
591 =item spreadsheet_format [ OVERRIDE ]
593 Returns a hashref of this user's Excel spreadsheet download settings:
594 'extension' (xls or xlsx), 'class' (Spreadsheet::WriteExcel or
595 Excel::Writer::XLSX), and 'mime_type'. If OVERRIDE is 'XLS' or 'XLSX',
596 use that instead of the user's setting.
600 # is there a better place to put this?
604 class => 'Spreadsheet::WriteExcel',
605 mime_type => 'application/vnd.ms-excel',
608 extension => '.xlsx',
609 class => 'Excel::Writer::XLSX',
610 mime_type => # it's on wikipedia, it must be true
611 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
615 sub spreadsheet_format {
617 my $override = shift;
620 || $self->option('spreadsheet_format')
621 || FS::Conf->new->config('spreadsheet_format')
629 Returns true if this user has the name of a known system account. These
630 users cannot log into the web interface and can't have passwords set.
636 return grep { $_ eq $self->username } ( qw(
647 =item change_password NEW_PASSWORD
651 sub change_password {
652 #my( $self, $password ) = @_;
653 #FS::Auth->auth_class->change_password( $self, $password );
654 FS::Auth->auth_class->change_password( @_ );
657 =item change_password_fields NEW_PASSWORD
661 sub change_password_fields {
662 #my( $self, $password ) = @_;
663 #FS::Auth->auth_class->change_password_fields( $self, $password );
664 FS::Auth->auth_class->change_password_fields( @_ );
673 L<FS::Record>, schema.html from the base documentation.