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

Revision as of 06:27, 24 March 2015

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.

agent_currency

Returns the FS::agent_currency objects (see FS::agent_currency), if any, for this agent.

agent_currency_hashref

Returns a hash references of supported additional currencies 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, payinfo, and thirdparty.

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', 'ECHECK', and 'PAYPAL' 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.

If thirdparty is set, the defined self-service payment gateway will be returned.

invoice_modes

Returns all FS::invoice_mode objects that are valid for this agent (i.e. those with this agentnum or null agentnum).

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_ordered_cust_main

Returns the number of ordered customers for this agent (customers with packages ordered, but not yet billed).

ordered_cust_main

Returns the ordered customers for this agent (customers with packages ordered, but not yet billed), 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.

num_on_hold_cust_pkg

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

num_not_yet_billed_cust_pkg

Returns the number of inactive customer packages (one-time packages otherwise unsuspended/uncancelled) 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.

num_sales

Returns the number of non-disabled sales people for this agent.

BUGS

SEE ALSO

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