Difference between revisions of "Freeside:3:Documentation:Developer/FS/agent"

Revision as of 20:03, 27 June 2012

NAME

FS::agent - Object methods for agent records

SYNOPSIS

 use FS::agent;

 $record = new FS::agent \%hash;
 $record = new FS::agent { 'column' => 'value' };

 $error = $record->insert;

 $error = $new_record->replace($old_record);

 $error = $record->delete;

 $error = $record->check;

 $agent_type = $record->agent_type;

 $hashref = $record->pkgpart_hashref;
 #may purchase $pkgpart if $hashref->{$pkgpart};

DESCRIPTION

An FS::agent object represents an agent. Every customer has an agent. Agents can be used to track things like resellers or salespeople. FS::agent inherits from FS::Record. The following fields are currently supported:

agentnum - primary key (assigned automatically for new agents); agent - Text name of this agent; typenum - Agent type (see FS::agent_type); ticketing_queueid - Ticketing Queue; invoice_template - Invoice template name; agent_custnum - Optional agent customer (see FS::cust_main); disabled - Disabled flag, empty or 'Y'; prog - Deprecated (never used); freq - Deprecated (never used); username - (Deprecated) Username for the Agent interface; _password - (Deprecated) Password for the Agent interface

METHODS

new HASHREF

Creates a new agent. To add the agent to the database, see "insert".

insert

Adds this agent to the database. If there is an error, returns the error, otherwise returns false.

delete

Deletes this agent from the database. Only agents with no customers can be deleted. If there is an error, returns the error, otherwise returns false.

replace OLD_RECORD

Replaces OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.

check

Checks all fields to make sure this is a valid agent. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.

agent_type

Returns the FS::agent_type object (see FS::agent_type) for this agent.

agent_cust_main

Returns the FS::cust_main object (see FS::cust_main), if any, for this agent.

pkgpart_hashref

Returns a hash reference. The keys of the hash are pkgparts. The value is true if this agent may purchase the specified package definition. See FS::part_pkg.

ticketing_queue

Returns the queue name corresponding with the id from the ticketing_queueid field, or the empty string.

payment_gateway [ OPTION => VALUE, ... ]

Returns a payment gateway object (see FS::payment_gateway) for this agent.

Currently available options are nofatal, invnum, method, and payinfo.

If nofatal is set, and no gateway is available, then the empty string will be returned instead of throwing a fatal exception.

If invnum is set to the number of an invoice (see FS::cust_bill) then an attempt will be made to select a gateway suited for the taxes paid on the invoice.

The method and payinfo options can be used to influence the choice as well. Presently only 'CC' and 'ECHECK' methods are meaningful.

When the method is 'CC' then the card number in payinfo can direct this routine to route to a gateway suited for that type of card.

num_prospect_cust_main

Returns the number of prospects (customers with no packages ever ordered) for this agent.

prospect_cust_main

Returns the prospects (customers with no packages ever ordered) for this agent, as cust_main objects.

num_active_cust_main

Returns the number of active customers for this agent (customers with active recurring packages).

active_cust_main

Returns the active customers for this agent, as cust_main objects.

num_inactive_cust_main

Returns the number of inactive customers for this agent (customers with no active recurring packages, but otherwise unsuspended/uncancelled).

inactive_cust_main

Returns the inactive customers for this agent, as cust_main objects.

num_susp_cust_main

Returns the number of suspended customers for this agent.

susp_cust_main

Returns the suspended customers for this agent, as cust_main objects.

num_cancel_cust_main

Returns the number of cancelled customer for this agent.

cancel_cust_main

Returns the cancelled customers for this agent, as cust_main objects.

num_active_cust_pkg

Returns the number of active customer packages for this agent.

num_inactive_cust_pkg

Returns the number of inactive customer packages (one-time packages otherwise unsuspended/uncancelled) for this agent.

num_susp_cust_pkg

Returns the number of suspended customer packages for this agent.

num_cancel_cust_pkg

Returns the number of cancelled customer packages for this agent.

generate_reg_codes NUM PKGPART_ARRAYREF

Generates the specified number of registration codes, allowing purchase of the specified package definitions. Returns an array reference of the newly generated codes, or a scalar error message.

num_reg_code

Returns the number of unused registration codes for this agent.

num_prepay_credit

Returns the number of unused prepaid cards for this agent.

BUGS

SEE ALSO

FS::Record, FS::agent_type, FS::cust_main, FS::part_pkg, schema.html from the base documentation.