nit
[freeside.git] / 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 agemtnum - 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 =back
54
55 =head1 METHODS
56
57 =over 4
58
59 =item new HASHREF
60
61 Creates a new agent.  To add the agent to the database, see L<"insert">.
62
63 =cut
64
65 sub table { 'agent'; }
66
67 =item insert
68
69 Adds this agent to the database.  If there is an error, returns the error,
70 otherwise returns false.
71
72 =item delete
73
74 Deletes this agent from the database.  Only agents with no customers can be
75 deleted.  If there is an error, returns the error, otherwise returns false.
76
77 =cut
78
79 sub delete {
80   my $self = shift;
81
82   return "Can't delete an agent with customers!"
83     if qsearch( 'cust_main', { 'agentnum' => $self->agentnum } );
84
85   $self->SUPER::delete;
86 }
87
88 =item replace OLD_RECORD
89
90 Replaces OLD_RECORD with this one in the database.  If there is an error,
91 returns the error, otherwise returns false.
92
93 =item check
94
95 Checks all fields to make sure this is a valid agent.  If there is an error,
96 returns the error, otherwise returns false.  Called by the insert and replace
97 methods.
98
99 =cut
100
101 sub check {
102   my $self = shift;
103
104   my $error =
105     $self->ut_numbern('agentnum')
106       || $self->ut_text('agent')
107       || $self->ut_number('typenum')
108       || $self->ut_numbern('freq')
109       || $self->ut_textn('prog')
110   ;
111   return $error if $error;
112
113   return "Unknown typenum!"
114     unless $self->agent_type;
115
116   '';
117
118 }
119
120 =item agent_type
121
122 Returns the FS::agent_type object (see L<FS::agent_type>) for this agent.
123
124 =cut
125
126 sub agent_type {
127   my $self = shift;
128   qsearchs( 'agent_type', { 'typenum' => $self->typenum } );
129 }
130
131 =item pkgpart_hashref
132
133 Returns a hash reference.  The keys of the hash are pkgparts.  The value is
134 true if this agent may purchase the specified package definition.  See
135 L<FS::part_pkg>.
136
137 =cut
138
139 sub pkgpart_hashref {
140   my $self = shift;
141   $self->agent_type->pkgpart_hashref;
142 }
143
144 =back
145
146 =head1 VERSION
147
148 $Id: agent.pm,v 1.2 2000-12-03 13:45:15 ivan Exp $
149
150 =head1 BUGS
151
152 =head1 SEE ALSO
153
154 L<FS::Record>, L<FS::agent_type>, L<FS::cust_main>, L<FS::part_pkg>, 
155 schema.html from the base documentation.
156
157 =cut
158
159 1;
160