FS/FS/agent.pm

   1 package FS::agent;
   2
   3 use strict;
   4 use vars qw( @ISA );
   5 use FS::Record qw( qsearch qsearchs );
   6 use FS::cust_main;
   7 use FS::agent_type;
   8
   9 @ISA = qw( FS::Record );
  10
  11 =head1 NAME
  12
  13 FS::agent - Object methods for agent records
  14
  15 =head1 SYNOPSIS
  16
  17   use FS::agent;
  18
  19   $record = new FS::agent \%hash;
  20   $record = new FS::agent { 'column' => 'value' };
  21
  22   $error = $record->insert;
  23
  24   $error = $new_record->replace($old_record);
  25
  26   $error = $record->delete;
  27
  28   $error = $record->check;
  29
  30   $agent_type = $record->agent_type;
  31
  32   $hashref = $record->pkgpart_hashref;
  33   #may purchase $pkgpart if $hashref->{$pkgpart};
  34
  35 =head1 DESCRIPTION
  36
  37 An FS::agent object represents an agent.  Every customer has an agent.  Agents
  38 can be used to track things like resellers or salespeople.  FS::agent inherits
  39 from FS::Record.  The following fields are currently supported:
  40
  41 =over 4
  42
  43 =item agentnum - primary key (assigned automatically for new agents)
  44
  45 =item agent - Text name of this agent
  46
  47 =item typenum - Agent type.  See L<FS::agent_type>
  48
  49 =item prog - For future use.
  50
  51 =item freq - For future use.
  52
  53 =item disabled - Disabled flag, empty or 'Y'
  54
  55 =item username - Username for the Agent interface
  56
  57 =item _password - Password for the Agent interface
  58
  59 =back
  60
  61 =head1 METHODS
  62
  63 =over 4
  64
  65 =item new HASHREF
  66
  67 Creates a new agent.  To add the agent to the database, see L<"insert">.
  68
  69 =cut
  70
  71 sub table { 'agent'; }
  72
  73 =item insert
  74
  75 Adds this agent to the database.  If there is an error, returns the error,
  76 otherwise returns false.
  77
  78 =item delete
  79
  80 Deletes this agent from the database.  Only agents with no customers can be
  81 deleted.  If there is an error, returns the error, otherwise returns false.
  82
  83 =cut
  84
  85 sub delete {
  86   my $self = shift;
  87
  88   return "Can't delete an agent with customers!"
  89     if qsearch( 'cust_main', { 'agentnum' => $self->agentnum } );
  90
  91   $self->SUPER::delete;
  92 }
  93
  94 =item replace OLD_RECORD
  95
  96 Replaces OLD_RECORD with this one in the database.  If there is an error,
  97 returns the error, otherwise returns false.
  98
  99 =item check
 100
 101 Checks all fields to make sure this is a valid agent.  If there is an error,
 102 returns the error, otherwise returns false.  Called by the insert and replace
 103 methods.
 104
 105 =cut
 106
 107 sub check {
 108   my $self = shift;
 109
 110   my $error =
 111     $self->ut_numbern('agentnum')
 112       || $self->ut_text('agent')
 113       || $self->ut_number('typenum')
 114       || $self->ut_numbern('freq')
 115       || $self->ut_textn('prog')
 116   ;
 117   return $error if $error;
 118
 119   if ( $self->dbdef_table->column('disabled') ) {
 120     $error = $self->ut_enum('disabled', [ '', 'Y' ] );
 121     return $error if $error;
 122   }
 123
 124   if ( $self->dbdef_table->column('username') ) {
 125     $error = $self->ut_alphan('username');
 126     return $error if $error;
 127     if ( length($self->username) ) {
 128       $error = $self->ut_text('password'); # ut_text... arbitrary choice
 129     } else {
 130       $self->_password('');
 131     }
 132   }
 133
 134   return "Unknown typenum!"
 135     unless $self->agent_type;
 136
 137   $self->SUPER::check;
 138 }
 139
 140 =item agent_type
 141
 142 Returns the FS::agent_type object (see L<FS::agent_type>) for this agent.
 143
 144 =cut
 145
 146 sub agent_type {
 147   my $self = shift;
 148   qsearchs( 'agent_type', { 'typenum' => $self->typenum } );
 149 }
 150
 151 =item pkgpart_hashref
 152
 153 Returns a hash reference.  The keys of the hash are pkgparts.  The value is
 154 true if this agent may purchase the specified package definition.  See
 155 L<FS::part_pkg>.
 156
 157 =cut
 158
 159 sub pkgpart_hashref {
 160   my $self = shift;
 161   $self->agent_type->pkgpart_hashref;
 162 }
 163
 164 =back
 165
 166 =head1 VERSION
 167
 168 $Id: agent.pm,v 1.5 2003-09-29 05:51:50 ivan Exp $
 169
 170 =head1 BUGS
 171
 172 =head1 SEE ALSO
 173
 174 L<FS::Record>, L<FS::agent_type>, L<FS::cust_main>, L<FS::part_pkg>,
 175 schema.html from the base documentation.
 176
 177 =cut
 178
 179 1;
 180